Overview:
- What’s new in Umbraco Forms 10.2?
- AJAX/Headless Form Rendering and Submission
- Data Retention Settings
- "Magic string" Formatting
- Block List Label for Forms
- Configuration of Field and Workflow Settings
- Options for Prevalue Text File Storage
- Other Updates
- How to test
- How to get your hands on the Release Candidate
- When is the Public Release?
As we discussed in the announcement of the last release, we are focusing on new features now on Umbraco 10 (and beyond), so this feature release is only for that version. Versions of Forms that run on older versions of Umbraco will continue to be patched for regressions, security issues, or significant bug fixes, as per the documented support policy.
As with previous releases, we are issuing this one first as a release candidate so you can evaluate what’s included and ideally try them out on your existing solutions. Of course, if you do find any issues, or simply have comments for further improvement on the new features, we welcome any feedback.
How to get access to the new version and where to submit any comments and report issues, is discussed at the bottom of the post.
Let’s have a look at what you can expect in this latest release 👀
What’s new in Umbraco Forms 10.2?
AJAX/Headless Form Rendering and Submission
Perhaps the most welcome feature included in this release, at least based on a small sample of discussions with customers, will be the support of AJAX or headless style form rendering and submission.
Umbraco of course provides Heartcore, a software as a service (SaaS) offering using Umbraco CMS, which is best suited for those projects going all-in on the headless approach, as it offers a content delivery platform, GraphQL, and other more advanced features.
However there are use cases within a traditional Umbraco setup, that whilst primarily using server-side page rendering with templates, has a need for "islands of rich functionality". Perhaps some features within the site will be implemented using a SPA framework and hence requires client-side handling for Forms, or you just want to be able to make an AJAX form post and avoid a full-page post back. These use cases are now supported directly within Umbraco Forms.
We've looked to align the API with similar plans for development within Heartcore and Umbraco CMS, so any use of Umbraco APIs are consistent in terms of request patterns, response codes, and handling of validation issues and exceptions. We also plan to ensure the API is precisely aligned with the upcoming version 3 of the Heartcore REST API, by adhering to the same schema, thus allowing even more familiarity when working across projects with either a traditional or headless Umbraco setup.
Working with the Forms API
To get started with working with the Forms API, there is of course documentation, as well as the Swagger definition that you can access once the release candidate is installed at the following path: /umbraco/forms/api/swagger/index.html
From there you'll see there are two API endpoints available:
Requesting a Form Definition
The first API endpoint accepts a GET request with a GUID provided in the query string that identifies a particular form. Optionally the integer or GUID id for a content page can be provided too. This will be used for applying "magic string" replacements based on the current Umbraco page.
GET /umbraco/forms/api/v1.0/definitions/{id}?contentId={contentId}
If the form is found, the response will contain a JSON representation of the form definition, including all pages, field sets, fields, and conditions. If not found, a 404 result will be returned.
Submitting an Entry
To submit an entry, the second API endpoint is used. This also expects the form's ID to be provided in the query string, and accepts a POST request containing the values of the form submission.
POST /umbraco/forms/api/v1.0/entries/{id}
An example request body might look like this:
As you see, the main part of the request consists of a set of key/value pairs, providing the field alias and the value completed by the user filling out the form. Each value can either be a string, or an array of strings. In this way, we support fields that accept multiple values, such as checkbox lists.
A successfully submitted entry will return a 202 "Accepted" status code, and one that fails validation rules a 422 "Unprocessable Entity" response containing a response body with details of the issues that need to be resolved.
Sample Code
To get started working with the API, we've created an illustrative example showing how a form can be rendered, validated, and submitted using the API and vanilla JavaScript. It's available at this gist.
Obviously, a feature like this really needs people using it to ensure we've hit the mark in terms of the information made available and the features supported. So we particularly welcome any feedback here, whether it's in the release candidate period or longer term as you start to use the feature after its full release.
Data Retention Settings
In order to ensure compliance with data privacy concerns, it can be useful to ensure data collected via form submissions is periodically cleaned up. Oftentimes it's not necessary to keep form entries forever, and so with this release we now allow you to configure rules for automated deletion of this data.
This is a destructive operation of course, so first of all you will need to opt-in to using it, by setting the Umbraco:Forms:Options:ScheduledRecordDeletion:Enabled setting to true.
With that in place, when amending the settings for a form, rather than seeing the following notice:
You will be able to provide a number of days to keep both submitted and approved entries for, on a per-form basis:
Further customization is available via configuration. Firstly, you can set defaults for newly created forms via the DaysToRetainSubmittedRecordsFor and DaysToRetainApprovedRecordsFor keys found within Umbraco:Forms:FormDesign:Defaults.
And you can control when and how often the scheduled background task actually deletes the records via the FirstRunTime and Period settings within Umbraco:Forms:Options:ScheduledRecordDeletion.
Documentation for these settings can be found on this page.
"Magic string" Formatting
Umbraco Forms has a useful feature for replacing placeholder strings at runtime with the values derived from different sources, such as the HTTP context or the current page. These are known as "magic strings".
Until now the replacements were "as is", with the placeholder replaced by the raw value obtained from the source. With this release, we've introduced the ability to format these values, such that for example dates, numbers, currencies and strings can be rendered in a more appropriate manner.
Using Magic String Formatters
These work like AngularJs filters in terms of syntax so should hopefully be familiar to many Umbraco developers.
For example, to truncate a string value obtained from a page property with the alias "title", you could apply a magic string of:
[#title | truncate: 100]
This release of Umbraco Forms ships with filters for changing the case of strings and formatting numbers, currencies, and dates. Please see this documentation page for more details.
Creating Magic String Formatters
As well as the format options available with Forms, it's also possible to create your own via C# code. This works in a similar way to other extension options available, where you create a class implementing a specific interface - in this case IParsedPlaceholderFormatter - and register it as part of application startup.
The interface requires that you provide a name that the user will use to apply the formatter, and a function that takes the raw string value and formats it as appropriate.
Documentation for this extension point is available here.
Block List Label for Forms
When working with the Block List list editor in Umbraco, the editor experience can be enhanced by defining a label for the appearance of the Block.
These labels can contain AngularJS filters, and with this release, we will ship one that can be used to extract the form name from a fom picker referenced in the label template.
For example, assuming a property containing a picked form with an alias of "contactForm", the
By using the filter as follows, the form's name will be displayed instead.
Configuration of Field and Workflow Settings
We've had a few requests for the ability to hide or modify certain settings that are applied to form fields and workflows, such as removing the ability to set the sender address on an email workflow, or being able to provide preset magic strings within certain fields.
We have introduced a feature with this release to be able to do this in a generic way, via configuration.
By default, with no configuration applied, settings operate as they do today. All settings are available for entry and are empty when added to a form.
If appropriate configuration is applied though, specific settings can be hidden from editors (so they will be stored with their default, empty value). It's also possible to provide a default value for settings, and if this is done, also make the field read-only. That way a value can be preset that the editor can modify if appropriate, or can be set to a fixed value if not.
Configuration is applied to one of four dictionaries - one for each of the types that have settings: fields, workflows, data sources, and prevalue sources. Each dictionary can be identified using the GUID or alias of the type as the key. The value is set to the following structure that contains three settings:
- IsHidden - if provided and set to true the setting will be hidden and will always have an empty value.
- DefaultValue - if provided the value will be pre-filled when a type using it is created.
- IsReadOnly - used in conjunction with the above, if set the field won't be editable and hence whatever is set as the default value won't be able to be changed. If set to false (or omitted) the editor can change the value from the provided default.
It's probably easiest to see both the configuration method and value this feature adds via example, so here are a couple.
In this example, the sender address field on a workflow for sending emails is hidden, such that the system-configured value is always used:
Here an organization-approved reCAPTCHA score threshold is defined, that can't be changed by editors:
More detail on these options can be found in the documentation, along with all the aliases, IDs and property names for the types shipped with Umbraco Forms, that you would need for applying this configuration.
Options for Prevalue Text File Storage
Umbraco Forms contains a built-in "Get value from text file" prevalue source type that stores the uploaded text file into the physical file system. This isn't ideal in some scenarios - for example when load balancing, or doing automated deployments from source control.
To store these files in an alternative location, you can replace the default implementation by writing and registering your own IPreValueTextFileStorage implementation.
To make this easier, with this release you are able to use or inherit from PreValueTextFileSystemStorage to change the underlying IFileSystem that's used to store the prevalue text files.
More documentation of this class and how to use it to save files into the configured media system can be found here.
Other Updates
The other updates included in the release are as follows:
- Improved the messaging displayed to the editor when applying a condition on an empty value.
- Set HTML field type for email fields in the provided form templates.
- Added support for custom icons for custom field types.
- Added configuration to remove the provided email and form templates from selection. See documentation on these settings here.
- Added the option for a drop-down prompt.
- Added details of the current form to the field's view model.
- For multi-page forms, skip pages that contain no visible fields due to conditions.
- A member key has been added to the RecordFilter object, used when programmatically retrieving a filtered set of form entries.
- Improved condition label display when matching on an empty value.
- Added documentation and base class to allow users to more easily change the location of prevalue source text files.
- Added configurable prefix for form element Ids.
See documentation on this setting here.
How to Test
You can either create a new installation using the package available from the link below or upgrade an existing project. Both scenarios can provide valuable feedback. If upgrading, you may find you need to update your cache buster version number.
If you find anything in the release candidate that is not working as you’d expect, we’d be grateful for feedback on the GitHub issue trackers for Forms. You’re welcome to add comments to the features and fixes listed linked above or to submit new bug reports (click New Issue and select Bug Report), please prefix the issue with 10.2RC.
How to get your hands on the Release Candidate
For Forms, release notes can be found on the our.umbraco.com download page. The release candidate is available from the usual NuGet feed.
When is the Public Release?
We’re aiming for a full public release on Tuesday, 8th November 2022, when the package will be available for new and existing projects on Umbraco Cloud and via NuGet.
A big H5YR 🙌 to everyone who has contributed to these releases by highlighting pain points, reporting issues, providing feedback, and suggesting solutions. And thanks to everyone willing to lend a hand in testing it out.
Bug reports are best handled on the issue tracker and as always, we welcome you to submit product feedback and questions to product@umbraco.com.
