Technical Documentation

Creating forms

First, go to the Content section and create a new item under Content by selecting "UForm Kit" document type. We will name it UForm Kit in this example.

After that, add child item under UForm Kit by selecting "UForm" document type. We will name it Contact.

Default contact form is now created and can be customized by changing form or email templates.

Form template

In Template tab, you can add a new form fields by creating a new form-tags and inserting them into the form template.

A form-tag acts as a placeholder for HTML form controls, such as a text input field, or for a collection of controls like a group of checkboxes. These form-tags are substituted with actual HTML code during the form rendering process.

It's important to adhere to a particular syntax rule for form-tags to function correctly, for example, [text* your-name]. However, memorizing this syntax is not essential as users have access to tag-generator tools. These tools are designed to create the correct form-tags, simplifying the process and ensuring functionality.

Note that changes in a form template are not automatically reflected in the mail settings of the contact form.

Form-tag syntax

The structure of a form tag can be broken down into four distinct components: type, name, options, and values.

• The 'type' is crucial, as it determines the HTML element that the tag will transform into and the kind of input it will accept.

• The 'name' serves as an identifier for the input field. While most form tags include a name, there are some exceptions.

• 'Options' are used to define the behavior and appearance of the form tag. These are not mandatory and can be included as needed.

• 'Values' generally set default values, although their use can vary depending on the tag's type. Like options, values are also optional.

It's important to follow the correct order when constructing a form tag. Options cannot precede the name, and values cannot be placed before options. This sequence is essential for the proper functioning of the form tag.

List of form-tag types

• Text fields (text, text*, email, email*, tel, tel*, url, url*, textarea and textarea*)

• Number fields (number, number*, range and range*)

• Date field (date and date*)

• Checkboxes, radio buttons, and menus (checkbox, checkbox*, radio, select and select*)

• File uploading field (file and file*)

• Acceptance checkbox (acceptance)

• Submit button (submit)

• Hidden (hidden)

Text fields

Various form-tags can be used to represent text input fields: text fields (text and text*), email fields (email and email*), telephone number fields (tel and tel*), URL fields (url and url*), and text areas (textarea and textarea*).

Text field

Form-tags text and text* are used for creating single-line input fields that accept any textual input. Form-tag text* is a required field.

OPTION	DESCRIPTION	EXAMPLE
id:(id)	Specifies id of the input element	id:test
class:(class)	Specifies class of the input element. Multiple classes can be assigned, like this: class:nice class required	class:nice
size:(num)	Specifies the width of the input element(size attribute). Default value is 40	size:40
minlength:(num)	Specifies the minimum length allowed for the input element	minlength:10
maxlength:(num)	Specifies the maximum length allowed for the input element	maxlength:40
placeholder	If this option is used, default value text will be used as placeholder

Example:

[text your-subject class:required "Contact"]

You can include form-tag text by selecting the "text" button in the tools section and then filling in the generated form.

Email field

Form-tags emailand email* are used for creating single-line input fields that accept only email addresses. Form-tag email* is a required field.

OPTION	DESCRIPTION	EXAMPLE
id:(id)	Specifies id of the input element	id:test
class:(class)	Specifies class of the input element. Multiple classes can be assigned, like this: class:nice class required	class:nice
size:(num)	Specifies the width of the input element(size attribute). Default value is 40	size:40
minlength:(num)	Specifies the minimum length allowed for the input element	minlength:10
maxlength:(num)	Specifies the maximum length allowed for the input element	maxlength:40
placeholder	If this option is used, default value text will be used as placeholder

Example:

[email* your-email "[e-mail]"]

You can include form-tag emailby selecting the "email" button in the tools section and then filling in the generated form.

URL field

Form-tags urland url* are used for creating single-line input fields that accept only URL. Form-tag url* is a required field.

OPTION	DESCRIPTION	EXAMPLE
id:(id)	Specifies id of the input element	id:test
class:(class)	Specifies class of the input element. Multiple classes can be assigned, like this: class:nice class required	class:nice
size:(num)	Specifies the width of the input element(size attribute). Default value is 40	size:40
minlength:(num)	Specifies the minimum length allowed for the input element	minlength:10
maxlength:(num)	Specifies the maximum length allowed for the input element	maxlength:40
placeholder	If this option is used, default value text will be used as placeholder

Example:

[url your-url "http://test.com"]

You can include form-tag url by selecting the "url" button in the tools section and then filling in the generated form.

Telephone number field

Form-tags tel and tel* are used for creating single-line input fields that accept only phone number. Form-tag tel* is a required field.

OPTION	DESCRIPTION	EXAMPLE
id:(id)	Specifies id of the input element	id:test
class:(class)	Specifies class of the input element. Multiple classes can be assigned, like this: class:nice class required	class:nice
size:(num)	Specifies the width of the input element(size attribute). Default value is 40	size:40
minlength:(num)	Specifies the minimum length allowed for the input element	minlength:10
maxlength:(num)	Specifies the maximum length allowed for the input element	maxlength:40
placeholder	If this option is used, default value text will be used as placeholder

Example:

[text your-phone "111-222-333"]

You can include form-tag tel by selecting the "tel" button in the tools section and then filling in the generated form.

Textarea

Form-tags textarea and textarea* are used for creating multi-line input . Form-tag textarea* is a required field.

OPTION	DESCRIPTION	EXAMPLE
id:(id)	Specifies id of the input element	id:test
class:(class)	Specifies class of the input element. Multiple classes can be assigned, like this: class:nice class required	class:nice
cols:(num)	Specifies the width of the text area(cols attribute). Default value is 40	size:40
rows:(num)	Specifies the number of lines in the text area(rows attribute). Default value is 40	rows:10
minlength:(num)	Specifies the minimum length allowed for the input element	minlength:10
maxlength:(num)	Specifies the maximum length allowed for the input element	maxlength:40
placeholder	If this option is used, default value text will be used as placeholder

Example:

[textarea* your-message "Enter text..."]

You can include form-tag textarea by selecting the "textarea" button in the tools section and then filling in the generated form.

Character count

For a character count feature in an input field with the maxlength attribute, you can utilize the count form-tag. This tag serves as a placeholder for displaying the number of characters typed, and it must have the same name as the corresponding input field.

Assuming you have an input field like this (with name="your-message"):

[textarea* your-message maxlength:40]
[count your-message]

To include a character count for this field, insert the [count your-message] tag:

[textarea* your-message maxlength:40]
[count your-message]

If you prefer to show the remaining character count up to the maxlength, you can achieve this by adding the down option to the count form-tag:

[textarea* your-message maxlength:40]
[count your-message down]

Number fields

Two form-tags are available for handling number fields: number and range. These align with the HTML5 input types 'number' and 'range'. Generally, a number input is presented as a spinner control, whereas a range input is commonly depicted as a slider control.

Form-tags number* and range* are a required fields.

OPTION	DESCRIPTION	EXAMPLE
id:(id)	Specifies id of the input element	id:test
class:(class)	Specifies class of the input element. Multiple classes can be assigned, like this: class:nice class required	class:nice
min:(num)	Specifies the minimum value allowed (min attribute)	min:10
max:(num)	Specifies the minimum value allowed (max attribute)	max:100
step:(num)	Specifies the interval between legal numbers. If step is 5, legal numbers could be 0, 5, 10, etc.	step:5
placeholder	If this option is used, default value text will be used as placeholder

Examples:

[number your-number min:10 max:100 "50"]
[range your-number min:10 max:100 "50"]

Both form-tags can also be added to a form by clicking on "number" button in the tools section and selecting desired filed type.

Date field

The form-tags date and date* align with the HTML5 input type 'date'. When providing a value in a date field, it must be in YYYY-MM-DD format as per the HTML5 specification. In most instances, managing this format is unnecessary, as the browser's date picker UI automatically sets the value in the correct format.

OPTION	DESCRIPTION	EXAMPLE
id:(id)	Specifies id of the input element	id:test
class:(class)	Specifies class of the input element. Multiple classes can be assigned, like this: class:nice class required	class:nice
min:(date)	Specifies the minimum value allowed (min attribute)	min:2023-01-01
max:(date)	Specifies the minimum value allowed (max attribute)	max:2024-01-01
placeholder	If this option is used, default value text will be used as placeholder

Example:

[date your-date min:2023-01-01 max:2024-01-01 "2023-04-01"]

You can include form-tag dateby selecting the "date" button in the tools section and then filling in the generated form.

Checkboxes, radio buttons and menus

There are several types of form-tags for representing checkboxes, radio buttons, and drop-down menus.

Checkboxes

Both checkbox and checkbox* align with the HTML input type 'checkbox'. checkbox* requires the user to check at least one of the boxes.

OPTION	DESCRIPTION	EXAMPLE
id:(id)	Specifies id of the input element	id:test
class:(class)	Specifies class of the input element. Multiple classes can be assigned, like this: class:nice class required	class:nice
default:(date)	Specifies options that are preselected. The integer following 'default:' indicates the position in the order of items, where 1 represents the first one. To select two or more items, concatenate integers with underscores (_), such as 'default:1_2_3'.	default:1 default:1_2
label_first	Typically, a checkbox is positioned first, followed by the label. However, by including the 'label_first' option, you have the ability to reverse their order.
use_label_element	Enclose each checkbox within a <label> tag
exclusive	This implies that when you choose a checkbox within a group, others will be deselected, allowing the group to maintain either a zero-selected or one-selected state only.
query	Retrieve values from the database by formulating an SQL query.	query:select Name from City

Example:

[checkbox your-color "Red" "Blue" "Green"]

You can include form-tag checkboxes by selecting the "checkboxes" button in the tools section and then filling in the generated form.

Radio buttons

Form-tag radio represents HTML input type 'radio'. As a group of radio buttons inherently requires a selection, a radio form-tag functions as a mandatory field. It is recommended to preselect an option within a radio button group using the 'default:1' option.

OPTION	DESCRIPTION	EXAMPLE
id:(id)	Specifies id of the input element	id:test
class:(class)	Specifies class of the input element. Multiple classes can be assigned, like this: class:nice class required	class:nice
default:(date)	Specifies options that are preselected. The integer following 'default:' indicates the position in the order of items, where 1 represents the first one.	default:1
label_first	Typically, a radio button is positioned first, followed by the label. However, by including the 'label_first' option, you have the ability to reverse their order.
use_label_element	Enclose each , radio button within a <label> tag
query	Retrieve values from the database by formulating an SQL query.	query:select Name from City

Example:

[radio your-color use_label_element default:1 "Red" "Blue" "Green"]

You can include form-tag radio buttons by selecting the "radio buttons" button in the tools section and then filling in the generated form.

Drop-down menus

Both select and select* indicate a drop-down menu ( in HTML). The select* option mandates that the user selects at least one option from the menu.

OPTION	DESCRIPTION	EXAMPLE
id:(id)	Specifies id of the input element	id:test
class:(class)	Specifies class of the input element. Multiple classes can be assigned, like this: class:nice class required	class:nice
default:(date)	Specifies options that are preselected. The integer following 'default:' indicates the position in the order of items, where 1 represents the first one.	default:1
multiple	Specifies that multiple options can be selected at once
include_blank	Add an empty item at the beginning of the options in this dropdown menu.
query	Retrieve values from the database by formulating an SQL query.	query:select Name from City

Example:

[select your-color "Red" "Blue" "Green"]

You can include form-tag drop-down by selecting the "drop-down" button in the tools section and then filling in the generated form.

File uploading field

With this feature, you can allow your users to upload their files via your form, and then an email with attachments of the files is sent to you.

Both fileand file* represent HTML input type file. file* requires the user to upload file.

OPTION	DESCRIPTION	EXAMPLE
id:(id)	Specifies id of the input element	id:test
class:(class)	Specifies class of the input element. Multiple classes can be assigned, like this: class:nice class required	class:nice
filetypes:(filetypes)	Specifies acceptable file types by listing them after the 'filetypes:' keyword. If you have multiple file types to set, separate them using a | (pipe) character.	filetypes:pdf|txt
limit:(num)	Specifies the maximum acceptable file size. Optionally, you can use the kb (kilobyte) or mb (megabyte) suffix. If you omit the suffix, the number is interpreted as bytes.	limit:1MB limit:500KB

Example:

[file your-file filetypes:pdf|txt limit:1mb]

You can include form-tag file by selecting the "file" button in the tools section and then filling in the generated form.

Acceptance checkbox

An acceptance checkbox is a simple checkbox dedicated to confirming the submitter’s consent for a specific condition. To use an acceptance checkbox in your contact form, simply insert an acceptance form-tag.

OPTION	DESCRIPTION	EXAMPLE
id:(id)	Specifies id of the input element	id:test
class:(class)	Specifies class of the input element. Multiple classes can be assigned, like this: class:nice class required	class:nice
optional	By default, an acceptance checkbox functions as a required field. If you explicitly set the 'optional' option, the checkbox operates as an optional field.	filetypes:pdf|txt

Example:

[acceptance your-consent] I accept terms. [/acceptance]

Note that, unlike other form-tag types, the [acceptance] tag is closed with a [/acceptance] tag at the end. The content between the opening and closing tags is the content of the form-tag.

You can include form-tag acceptance by selecting the "acceptance" button in the tools section and then filling in the generated form.

Submit button

Form-tag submit represents HTML input type sumbit.

OPTION	DESCRIPTION	EXAMPLE
id:(id)	Specifies id of the input element	id:test
class:(class)	Specifies class of the input element. Multiple classes can be assigned, like this: class:nice class required	class:nice

It is the only tag without name, but you can set its value. Example:

[submit "Send"]

You can include form-tag submit by selecting the "submit" button in the tools section and then filling in the generated form.

Hidden

A hidden field is used during a web form submission to include data that isn’t intended to be modifiable or viewable by the end user who submits the form.

Form-tag hidden represents HTML input type hidden.

OPTION	DESCRIPTION	EXAMPLE
id:(id)	Specifies id of the input element	id:test
class:(class)	Specifies class of the input element. Multiple classes can be assigned, like this: class:nice class required	class:nice

Example:

[hidden your-email "[e-mail]"]

You can include form-tag hidden by selecting the "hidden" button in the tools section and then filling in the generated form.

Form autocompletion

Text fields support the autocomplete option, allowing you to customize the behavior of autocompletion in the generated HTML.

For instance, if you wish to enable autocompletion for the user's name and set the autocomplete option to "name" in a form-tag, the code would look like this:

[text* your-name autocomplete:name]

The resulting HTML element output will include the autocomplete="name" attribute. In browsers that support autocompletion, this attribute prompts the browser to suggest the user's full name for input, enhancing the user experience.

reCAPTCHA (v3)

You can use reCAPTCHA module in your forms to protect you against spam and other types of automated abuse. Uform Kit uses reCAPTCHA v3 API.

First you need to go to reCAPTCHA Admin Console and register your site. Choose reCAPTCHA v3 from type options. After you register a website, you will get the site key and secret key for the site.

You should add them to your appsetings.json file, like this:

 "UFormKit": {
    "Recaptcha": {
      "SiteKey": "[your site key]",
      "SecretKey": "[your secret key]"
    }
  }

Now, go to Content section, select your contact form and check option Use recaptcha in Template tab.

Since version 1.0.4, we have integrated a scoring system into reCAPTCHA validation. By default, a threshold of 0.5 is used, but this value can be changed in the appsettings.json file like this:

"UFormKit": {
    "Recaptcha": {
     "ScoreThreshold": 0.3
    }
  }

Adjust the ScoreThreshold value as needed to customize the scoring system to your application's requirements.

Honeypot

Starting from version 1.0.6, we've added the 'Use Honeypot' option in the Template tab. When enabled, a honeypot field will be added to your form to help further prevent spam.

Cloudflare Turnstile

Starting with version 1.0.9, UForm Kit includes built-in support for Cloudflare Turnstile — a privacy-focused CAPTCHA alternative that helps block bots and automated abuse.

Visit the Cloudflare Turnstile dashboard, under the Turnstile section, click "Add Widget," and configure it to get your Site Key and Secret Key.

You should add them to your appsetings.json file, like this:

 "UFormKit": {
    "CloudflareTurnstile": {
        "SiteKey": "[your site key]",
        "SecretKey": "[your secret key]"
    }
  }

Now, go to Content section, select your contact form and check option Use Cloudflare Turnstile in Template tab.

Displaying form on a page

There are two options to display form on a page: by using a a View Component or by using a macro.

Displaying form using a View Component

You can render form by calling a view component like this:

@await Component.InvokeAsync("UForm",new { id = ["form node id"]})

If you want to add a contact form as a property, you can use the existing Content Picker editor.

Go to the Settings section and select Document type where you want to add a contact form. Add a new property and select Content Picker for editor. In additional editor settings, we suggest checking Show open button and setting UForm Kit as Start node.

Now go back to the Content section and add desired contact form on your page.

Now, you can render a form by referencing a content picker editor:

@await Component.InvokeAsync("UForm",new { id = @Model.ContactForm.Id})

Displaying form using a macro

If you want to display a contact form with macro, use following:

@await Umbraco.RenderMacroAsync("insertUForm", new { formId = ["form node id"]})

Macro has only one parameter formId, which represents Id of contact form

Form Validation

UKitForm is using jquery validation plugin to validate contact forms. These client dependencies shoul be added to View:

• jQuery

• jQuery validate

• jQuery validate unobtrusive

Example:

<script src="https://ajax.aspnetcdn.com/ajax/jQuery/jquery-3.7.1.min.js"></script>
<script src="https://ajax.aspnetcdn.com/ajax/jquery.validate/1.19.2/jquery.validate.min.js"></script>
<script src="https://ajax.aspnetcdn.com/ajax/mvc/5.2.3/jquery.validate.unobtrusive.min.js"></script>

Setting up mail

SMTP server configuration

First, you should configure your SMTP server in appsettings.json file, under Umbraco:CMS:Global:Smtp section. For more information, check this link.

Mail-tags

A mail-tag within a template is notably more straightforward than a form-tag, consisting of just a single word, usually corresponding to the form-tag's name. This word will be substituted with the corresponding form input during the process.

If you have form-tag:

[text* your-subject class:required "Contact"]

corresponding mail-tag would be [your-subject].

Mail template

In Mail tab, user can edit email template including message body, file attachments an message header fields.

To field

Set the recipient email address here. Mail-tag can be used for this field.

From field

Set the sender email address here. Default value is Umbraco:CMS:Global:Smtp:From from you appsettings.json file.

Subject field

Set the subject of the message here. Mail-tag can be used here, e.g [your-subject]

Cc field

Set the CC recipient to the email message. Mail-tag can be used for this field.

Bcc field

Set the BCC recipient to the email message. Mail-tag can be used for this field.

Reply to

Set the address other than the From address to use to reply to this message. Mail-tag can be used for this field.

Message body

Set the message body here; you can add mail-tags anywhere in this field.

Should you select the "Exclude lines with blank mail-tags from output" checkbox, lines containing mail-tags with no values will be omitted from the actual email output's message body.

By default, plain text is employed for the message body. To use HTML instead, mark the "Use HTML content type" checkbox.

If the 'Exclude links from message' option is selected, all URLs will be removed from the message body.

File attachments

When attaching uploaded files to this email, insert mail-tags representing the uploaded files into the "File attachments" field. For instance, if you have a form-tag like this:

[file your-file limit:1MB]

the corresponding mail-tag is:

[your-file]

It's important to note that what you place in the "File attachments" field is [your-file] (mail-tag), not [file your-file limit:1MB] (which is a form-tag).

If you've uploaded multiple files and wish to include them all in an email, simply use a new line, as shown below:

Special mail-tags

Special mail-tags can be use in various sections of your form template to capture and include additional information beyond what's directly entered by the user (such as in the message body or other mail-related fields).

• [_remote_ip]: This mail-tag is substituted with the submitter’s IP address.

• [_user_agent]: Use this mail-tag to represent the submitter’s user agent information, which typically refers to their browser.

• [_url]: When included, this mail-tag gets replaced by the URL of the page where the contact form is embedded.

• [_date]: This mail-tag gets replaced by the date of the form submission.

• [_time]: Include this mail-tag to have it substituted with the time of the form submission.

Editing messages

You have the ability to modify messages utilized in different scenarios within the Messages tab. Certain messages serve as notifications to the sender regarding the status of the contact form, including:

• Thank you for your message. It has been sent.

Additionally, there are messages indicating validation errors in input fields:

• The field is required.

Additional settings

Additional settings can be set within the Additional settings tab:

Do not store data

If this option is checked, submitted messages won't be saved to the database.

Demo mode

By enabling the demo mode, your contact form will skip the typical process of sending emails. Instead, it provides a response message indicating that the submission has been "completed successfully."

It allows you to simulate successful form submissions without generating real email traffic during testing or demonstration phases.

Redirect to page

UForm Kit typically redirects to the same URL as the form's URL by default after form submissions

This redirection setup provides a way for you to tailor the post-submission experience for users, directing them to a customized "Thank You Page" or any other designated URL.

Block IP addresses

Since version 1.0.8, we have added the Block IP addresses option, which prevents submissions from specific IP addresses or ranges. You can enter a list of IPs or ranges, separated by commas. For example: 199.99.9.9, 133.33.33.*

Storing submitted messages

Since version 1.0.2, UForm Kit package stores submitted message in the database by default. You can see saved messages by clicking on desired form in the Content tab.

If you don’t want to store messages for certain contact forms, you can achieve this by checking the Do not store data in the contact form’s Additional Settings tab panel.

AJAX submissions

Our package supports AJAX submission. Since version 1.0.3 you can utilize the "/umbraco/UFormKit/UForm/SendJson" method, which returns a JSON result response. The response object includes properties such as "Success" indicating the success status and "Message" providing additional information.

Telemetry statistics

Since version 1.0.2, our UForm Kit package has been collecting telemetry data. This provides us with insights to which Umbraco and package versions being used, so that we can make informed decisions on how to focus our future development efforts. The data is sent anonymously, no personal or sensitive data is collected.

What type of data is being captured?

An example of the data captured is as follows.

{
    "umbraco_id": "0403E47E-EFE7-4CF2-8E97-148681DAFC10",
    "umbraco_version": "13.0.0",
    "package_id": "UForm Kit",
    "package_version": "1.0.2"
}

How to disable telemetry?

If you would prefer to opt-out and disable the telemetry feature, add this option in your appsettings.json file:

{
  "UFormKit": {
    "DisableTelemetry": true
  }
}

UFormEmailSentNotification

Starting from version 1.0.3, our package introduces a new feature: the custom UFormEmailSentNotification notification. This notification is triggered after the form has been successfully sent via email, allowing you to easily hook into this event.

public class UFormEmailSentNotification : INotification
{
    public IFormCollection Form { get; set; }

    public string Message { get; set; }

    public UFormEmailSentNotification(IFormCollection form, string message)
    {
        Form = form;
        Message = message;
    }
}