Adding A Field Type To Umbraco Forms
This builds on the "adding a type to the provider model" chapter
C#
Add a new class to the Visual Studio solution, make it inherit from Umbraco.Forms.Core.FieldType
, and fill in the constructor:
In the constructor, or via overridden properties, we can specify details of the field type:
Id
- should be set to a unique GUID.Alias
- an internal alias for the field, used for localized translation keys.Name
- the name of the field presented in the backoffice.Description
- the description of the field presented in the backoffice.Icon
- the icon of the field presented in the backoffice form builder user interface.DataType
- specifies the type of data stored by the field. Options areString
,LongString
,Integer
,DataTime
orBit
(boolean).SupportsMandatory
- indicates whether mandatory validation can be used with the field (defaults totrue
).MandatoryByDefault
- indicates whether the field will be mandatory by default when added to a form (defaults tofalse
).SupportsRegex
- indicates whether pattern based validation using regular expressions can be used with the field (defaults tofalse
).SupportsPreValues
- indicates whether prevalues are supported by the field (defaults tofalse
).FieldTypeViewName
- indicates the name of the partial view used to render the field.RenderInputType
- indicates how the field should be rendered within the theme, as defined with theRenderInputType
enum. The default isSingle
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.
Partial view
Then we will start building the view for the default theme of the Form at Views\Partials\Forms\Themes\default\FieldTypes\FieldType.MyCustomField.cshtml
.
The file name for the partial view should match the value set on the FieldTypeViewName
property.
This will be rendered when the default theme is used.
If working with Umbraco 9 or earlier versions, you'll find the Views\Partials\Forms\Themes\default\
folder on disk and can create the files there.
For Umbraco 10 and above, we've moved to distributing the theme as part of a Razor Class Library 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 article.
Umbraco backoffice view
The final step involves building the HTML view which will be rendered in Umbraco as an example of how our end result will look:
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
.
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.
To store in a different location, you can apply the following override to the custom field type's C# representation:
Field settings
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. These settings can be added as properties with a Setting
attribute:
The property Name
names the setting in the backoffice with the Description
providing the help text. Both of these are translatable by providing a user or package language file containing appropriate keys:
The area aliases for the other provider types are as follows:
Data sources -
formProviderDataSources
Export types -
formProviderExportTypes
Prevalue sources -
formProviderPrevalueSources
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\
.
Again though, you can use your own location, and configure with a full path to the view, e.g.:
To reference the file the setting should be configured with a full path to the view, e.g.:
SupportsPlaceholders
is a flag indicating whether the setting can contain "magic string" placeholders and controls whether they are parsed on rendering.
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).
IsMandatory
if set to true
will provide client-side validation in the backoffice to ensure the value is completed.
Settings when inheriting
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.
All setting properties for the Forms provider types are marked as virtual
, so you can override them and change the setting values:
If you want to hide a setting in your derived class you can use the IsHidden
property:
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. This rendering takes place 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.:
Last updated