In Umbraco Forms it's possible to customize the functionality with various configuration values.
With Umbraco Forms it's possible to customize the functionality with various configuration values.
All configuration for Umbraco Forms is held in the appSettings.json
file found at the root of your Umbraco website. If the configuration has been customized to use another source, then the same keys and values discussed in this article can be applied there.
The convention for Umbraco configuration is to have package based options stored as a child structure below the Umbraco
element, and as a sibling of CMS
. Forms configuration follows this pattern, i.e.:
All configuration for Forms is optional. In other words, all values have defaults that will be applied if no configuration is available for a particular key.
For illustration purposes, the following structure represents the full set of options for configuration of Forms, along with the default values. This will help when you need to provide a different setting to understand where it should be applied.
This configuration value expects a true
or false
value and can be used to disable the feature where all new forms are provided with a default "Consent for storing submitted data" field on creation. Defaults to false
.
This configuration value expects a true
or false
value and can be used to toggle if new forms that are created adds an email workflow to send the result of the form to the current user who created the form. Defaults to false
.
This setting controls the maximum number of columns that can be created by editors when they configure groups within a form. The default value used if the setting value is not provided is 12.
This setting allows you to configure the name of the theme to use when an editor has not specifically selected one for a form. If empty or missing, the default value of "default" is used. If a custom default theme is configured, it will be used for rendering forms where the requested file exists, and where not, will fall back to the out of the box default theme.
When creating an empty form, a single workflow is added that will send an email to the current user's address. By default, the template shipped with Umbraco Forms is available at Forms/Emails/Example-Template.cshtml
is used.
If you have created a custom template and would like to use that as the default instead, you can set the path here using this configuration setting.
From Forms 10.2, the provided template can be removed from the selection if you have created email templates for the "send Razor email" workflow. To do this, set this value to true
.
Similarly, from Forms 10.2, the provided form templates available from the form creation dialog can be removed from selection. To do this, set this configuration value to true
.
By default the value of HTML id
attribute rendered for fieldsets and fields using the default theme is the GUID associated with the form element. Although this is valid, some browsers, particularly Safari, may report issues with this if the identifier begins with a number. To avoid such issues, from Forms 10.2, the attribute values can be prefixed with the value provided in this configuration element.
For example, providing a value of "f_"
will apply a prefix of "f_" to each fieldset and field id
attribute.
Forms 10.2 introduced the ability to configure settings for the field, workflow, data source, and prevalue sources. The default behavior, when a new field or workflow is added to a form, is for each setting to be empty. The values are then completed by the editor. All settings defined on the type are displayed for entry.
In some situations, you may want to hide certain settings from entry, so they always take an empty value. In others, you may want to provide a default value that the editor can accept or amend. And lastly, you may have a requirement for a fixed, non-empty value, that's enforced by the organization and not editable. Each of these scenarios can be supported by this configuration setting.
It consists of four dictionaries, one for each type:
DataSourceTypes
FieldTypes
PrevalueSourceTypes
WorkflowTypes
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 DefaultValue
won't be able to be changed. If set to false (or omitted) the editor can change the value from the default.
In this example, the sender address field on a workflow for sending emails can be 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:
In order to configure this setting, you will need to know the GUID or alias for the type and the property name for each setting. You can find these values for the built-in Forms types here.
Take care to not hide any settings that are required for the particular field or workflow type (for example, the Subject
field for email workflows). If you do that, the item will fail validation when an editor tries to create it.
The default value and read-only settings apply to most setting types. There is an exception for complex ones where a default string value isn't appropriate. An example of one of these is the field mapper used in the "Send to URL" workflow.
The following configured values are applied to all forms as they are created. They can then be amended on a per-form basis via the Umbraco backoffice.
Once the form has been created, the values are set explicitly on the form, so subsequent changes to the defaults in configuration won't change the settings used on existing forms.