Forms in notifications
You can create forms in notifications to request information from users. Forms can be as simple or complex as your workflows require. The information users provide is passed back to your calling application when the user submits the form. Your app subscribes to form-related events to provide custom error handling and to get the form data to process.
How it works
In Notifications v2.2 or later, the form
property is available in the "custom"
template as well as the "markdown"
template. The same form field types and widget types are available in both.
A form object is an array of fields. Each field specifies the data type of the form field and the widget
that specifies the type of form field. The following widget
types are available:
-
"Checkbox"
. Data type"boolean"
-
"CheckboxGroup"
(new in Notifications v2.2). Data type"checkboxGroup"
-
"Date"
(new in Notifications v2.2). Data type"date"
-
"Dropdown"
(new in Notifications v2.2). Data type"string"
-
"Number"
. Data type"number"
-
"RadioGroup"
(new in Notifications v2.2) Data type"radioGroup"
-
"Text"
. In Notifications v2.2, also supports a text area with themultiline
property. Data type"string"
-
"Time"
(new in Notifications v2.2) Data type"time"
-
"Toggle"
. Data type"boolean"
Validation
A form field can include optional validation. Validation rules are specific to each data type. Each rule provides standard error strings if validation fails, or you can provide a custom string with the invalidMessage
value.
The DateField
, RadioGroupField,
CheckboxGroupField
, and TimeField
widgets support only the required
validation rule. For available validation rules for other form fields, see the API reference for each field.
In Notifications v2.2 or later, you can also write custom validation rules by monitoring the notification-form-values-changed
event and including the setErrors
method on the event object. See the API reference for this event, and the example on this page for a simple custom validation rule.
If any validation rule fails, the user cannot submit the form.
Submit and process the form
The entire form requires a button that includes the submit: true
and cta: true
properties. In Notifications v2.2 or later, A button.formOptions
property lets you specify different button text for different states of the form. See the API reference for ButtonOptions
. For information about monitoring different form states, see the section in this article on subscribing to form-related events.
How to do it
Create the form
The following example includes a markdown
template, but the same form definition could be used with a custom template. This example shows how to add different form fields. It is not intended to provide a real-world example. Some fields are included to help show how to write custom error handling.
const orderRequestForm: NotificationOptions =
{
template: "markdown",
toast: "sticky",
title: "Form Example",
indicator:
{
color: "purple"
text: "EXAMPLE"
},
icon: "oflogo.png",
form:
{
// whether required fields are marked as required in the notification
displayFieldRequirementStatus: true,
fields:
// array of form fields
[
// Dropdown form field
{
// key value is included in form events
key: "buy_option",
// label for the form field
label: "Order Type",
// data type
type: "string",
// widget object config
widget: {
type: "Dropdown",
options: [
{
label: "Option One",
value: "option_one"
},
{
label: "Option Two",
value: "option_two"
}
]
}
},
// Number form field
{
key: "share_quantity",
label: "Share Quantity",
type: "number",
widget: {
type: "Number",
min: 100
}
},
// Number form field with optional currencyChar property
// See API reference for other optional properties
{
key: "share_price",
label: "Share Price",
type: "number",
widget: {
type: "Number",
currencyChar: "$"
}
},
{
// Text form field with simple validation
key: "notes",
label: "Notes",
type: "string",
widget:
{
type: "Text",
placeholder: "Add notes here",
multiline: true,
rows: 4
},
validation:
{
max:
{
arg: 256,
invalidMessage: "Cannot be more than 256 characters"
}
}
},
{
// Text form field with custom validation
key: "sourceEmail",
type: "string",
label: "Email",
helperText: "We will use this email to send you the report after we crawl your website",
widget:
{
type: "Text"
},
validation:
{
required:
{
arg: true
}
}
}
],
}
buttons: [
{
title: "Submit",
iconUrl: "favicon.ico",
submit: true,
// for custom validation errors, you can also specify an errorTitle value
formOptions: { submittingTitle: "Submitting Form ...", successTitle: "Submitted" }
}
]
};
Subscribe to form-related events
To process the form, at a minimum you subscribe to the notification-form-submitted
event type so your app can handle the form data.
addEventListener("notification-form-submitted", (event: NotificationFormSubmittedEvent) =>
{
// example logs to console, but your app would process the form data as needed
console.log(`Form submitted: ${JSON.stringify(event.form)}`);
});
Here event.form
is a Record
, where key values are specified in the form definition, and field values are the values submitted by the user.
The default behavior is for the notification to be dismissed when it is submitted. In Notifications v2.2 or later, you can add the preventDefault
and formStatus
methods to your event handler. See the API reference for these methods. These methods let you monitor the status of the form submission if you provide values for the formOptions
property when you define the form.
You can also subscribe to the notification-form-values-changed
event to provide custom error handling. The following example validates the Email
text field specified in the form definition example.
const addEmailPhoneValidation = () => {
addEventListener(
'notification-form-values-changed',
async (formValueChanged: NotificationFormValuesChangedEvent) => {
const errors = [];
// Simple regular expression to check for a valid email address
const emailPattern = /^\S+@\S+\.\S+$/;
// Field to validate
const email = formValueChanged.form.sourceEmail as string;
// Validate email if it's not null or undefined
if (email && !emailPattern.test(email)) {
errors.push({
fieldKey: 'sourceEmail',
error: 'Invalid email format'
});
}
// If there are any errors, set them all at once
if (errors.length > 0) {
await formValueChanged.setErrors(errors);
}
}
);
};
Best practices
-
You can’t require that a user must submit a form, because the user can always dismiss the notification. Consider including an ‘ignore’ or ‘cancel’ button, so the user doesn’t have to hunt for the close button.
-
Make sure any custom validation messages (
invalidMessage
property) are clear, so the user knows exactly what is expected of them.
Updated 12 months ago