fd is a Form Manager that provides access to all events, containers, controls, fields, validators, and data of the form.
Whenever you want to manipulate your form, you must call the manager first.
// the form is ready
fd.rendered(() => {
// and its fields are available to get/set
fd.field('Title').value = 'New Title';
});
Note
fd is accessible globally on the Preview page, so you can run tests directly from the browser console (F12).
On this page, you will find information about fd properties, methods, and events.
fd has the following properties:
Gets the ID of the submission.
fd.submissionId; // '2021-12-30T13:40:22-4dcdad7b-6fdc-44ab-9789-cfd9118b6780'
Gets the current culture name. Can be used outside of all events to set the culture.
fd.culture; // returns 'en-US'
//run outside of all events
fd.culture = 'de-DE';
Gets the current language of the form. Can be used outside of all events to set the language.
fd.language; // returns 'en-US'
//run outside of all events
fd.language = 'de-DE';
Checks if the form is valid or not. The method returns a promise that is resolved when all form elements have been validated.
await fd.validate():
Gets an array of form validators. Can be used to add new ones. These validators are more complex than Field validators and are used to check that multiple fields have appropriate values. If the fields do not meet these criteria, the form will not submit.
// return form validators
fd.validators;
// add new form Validator
fd.validators.push({
name: 'MyCustomValidator',
error: 'Age must be 18 or over in order to subscribe',
validate: function(value) {
if (fd.field('Age').value < 18
&& fd.field('PaymentModel').value === 'Subscription')
return false;
return true;
}
});
The form validator function can also be asynchronous:
fd.validators.push({
name: 'MyCustomValidator',
error: 'This item is locked and cannot be modified anymore.',
validate: function() {
return new Promise(resolve => {
// make a request to SharePoint for checking the actual values of the current item.
window.setTimeout(() => {
resolve(false); // validation failed
// resolve(true) if validation passed
}, 500);
});
}
});
Gets the logged-in user (for forms that require authenitcation).
fd.account.username; // 'user@domain.com'
Gets language constants as an object. Can be used to set text for localization.
To change language constant, call the property inside fd.created event:
//how to change a message
fd.created(() => {
fd.messages.PlumsailForm_Submission_Success = 'Thank you!';
});
//all available messages:
fd.created(() => {
fd.messages.Captcha_Error = "Captcha is invalid."
fd.messages.DataTable_ColumnRequired = "This column is required"
fd.messages.DataTable_Filter_MultipleItemsSelected = "items selected"
fd.messages.DataTable_Filter_OneItemSelected = "item selected"
fd.messages.DataTable_Filter_SelectAll = "Select all"
fd.messages.Failure_AccessDenied = "You do not have permissions to perform this action."
fd.messages.Failure_General = "An error has occured. Please check the browser console (F12)."
fd.messages.Failure_ItemNotFound = "An item was not found. It may have been deleted or renamed by another user."
fd.messages.FileOrFolderNameForbiddenSymbols = "Please enter a name that doesn't start or end with a dot and doesn't include any of these characters: \" * : < > ? / \\ |."
fd.messages.MaxLengthUrlValidator_Error = "The value of this field may not contain more than {0} characters."
fd.messages.MultiChoice_SpecifyOwnValue = "Specify your own value:"
fd.messages.PlumsailForm_Authentication_Error = "Authentication error"
fd.messages.PlumsailForm_CorrectErrors = "Oops! There seem to be some errors below:"
fd.messages.PlumsailForm_Error_AccessDenied = "You do not have permissions to this form"
fd.messages.PlumsailForm_Error_AuthenticationLoop = "Error occured when trying to authenticate. Please refresh page or contact with form developer"
fd.messages.PlumsailForm_Error_FormAlreadySubmitted = "You've already submitted this form."
fd.messages.PlumsailForm_Error_NotFound = "The form was not found."
fd.messages.PlumsailForm_Error_Unhandled = "Something went wrong. Try again later..."
fd.messages.PlumsailForm_Note = "Note"
fd.messages.PlumsailForm_Submission_Btn = "Return to the form"
fd.messages.PlumsailForm_Submission_Error = "An error has occured while saving the form. Please check the console (F12)."
fd.messages.PlumsailForm_Submission_Success = "Thanks for submitting the form!"
fd.messages.PlumsailForm_Warning_NotiftySubscribersDisabled = "submissions are disabled for this form. Your data has not been saved."
fd.messages.RequiredValidator_Error = "This field is required."
fd.messages.Uploading_Error = "An error has occurred while uploading the file."
});
Holds the name or ID of the current form theme. Can be used to set theme dynamically.
//switch to a predefined theme by name
fd.theme = 'Plumsail'
//switching to a custom theme by ID
fd.theme = 'dfd4cfc38dc1735745ef623de3b56441'
fd has the following methods:
Saves the form as a draft. It is only available for forms with the Saving Drafts property enabled.
fd.saveDraft();
Gets data from all fields on the form. Can be also used to set multiple values at the same time.
// get data as an object
fd.data();
// set field values
fd.data({Field1: value1, Field2: value2});
Exports the current form to a PDF file. Accepts the following arguments:
file – a filename of the file.
options – options for the PDF file, such as paper size, margin, orientation, etc.
fd.exportToPDF('contacts-form', {
paperSize: 'A4',
landscape: false,
multiPage: true
});
Find more about PDF options in How to save form as PDF for printing.
fd has the following events:
Occurs prior to the form creation.
vueConfig passed as an argument to the handler is a configuration of the main vue-component. You can register your own child components. You can read more about it here.
Asynchronous event
Can return a Promise and the corresponding operation will not continue until the promise is resolved.
fd.beforeCreate((vueConfig) => {
console.log('beforeCreate');
console.log(vueConfig);
});
Occurs as soon as the form is created.
vue passed as an argument to the handler is a Vue instance of the form.
It is also available from fd variable this way: fd._vue
fd.created((vue) => {
console.log('created');
console.log(vue);
});
Occurs before mounting the vue-component to DOM.
vue passed as an argument to the handler is a Vue instance of the form.
It is also available from fd variable this way: fd._vue
Asynchronous event
Can return a Promise and the corresponding operation will not continue until the promise is resolved.
fd.beforeRender((vue) => {
console.log('beforeRender');
console.log(vue);
});
Occurs after mounting the vue-component to DOM.
Best place to run your JavaScript since all elements are mounted.
vue passed as an argument to the handler is a Vue instance of the form.
It is also available from fd variable this way: fd._vue
fd.rendered((vue) => {
console.log('rendered');
console.log(vue);
});
Occurs before submitting the form.
data passed as an argument to the handler is an object representing user’s input.
Keys are internal names of form fields, Values – user’s input:
{
Field1: 'text'
DateTime1: new Date('2017-01-01')
}
Here, you can modify form’s data with code before sending it to the server.
Asynchronous event
Can return a Promise and the corresponding operation will not continue until the promise is resolved.
fd.beforeSave((data) => {
console.log('beforeSave');
console.log(data);
});
//async check
fd.beforeSave((data) => {
return $.getJSON('https://mywebservice.contoso.com')
.then(function(result) {
if(result == null){
throw new Error('No results');
}
data.additionalProperties = result;
});
});
Occurs after the data is submitted.
Can be used to display confirmation messages after the form is saved or perform some other actions.
fd.saved(() => {
console.log('saved');
});
You can use this event to do something after the form has been saved. For example, you can get field values and redirect user to another URL with these field values as URL params:
fd.saved(() => {
var name = fd.field('Name').value;
var email = fd.field('Email').value;
var url = 'https://plumsail.com?name=' + name + '&email=' + email;
window.location.href = url;
});