JavaScript SDK for headless Optimizely Forms
17 min
Use JavaScript SDK
To use the JavaScript SDK, install @episerver/form-sdk (required) and @episerver/form-react (optional) if you are rendering with React. Then, add the Form component imported from @episerver/form-react along with the form key and base URL to render the form:
<Form
key={formKey}
formKey={formKey}
language={language ?? "en"}
baseUrl={process.env.REACT_APP_HEADLESS_FORM_BASE_URL ?? "/"}
identityInfo={identityInfo}
history={history}
currentPageUrl={pageUrl}
/>Form SDK
Properties of models.
- Form container model properties:
- Key – The GUID to identify the form
- Properties – Contains form-setting properties such as Title, Description, Success message, and so on.
- FormElements – Contains a list of form elements.
- Element block model properties:
- Key – The GUID to identify the element block.
- ContentType – Describes the type of element, TextboxElementBlock, SubmitButtonElementBlock, and so on.
- Properties – Contains other element properties such as Label, Placeholder, PredefinedValue, Validators (a list of validators to validate the element's input data), and so on.
- Validator model properties:
- Type – The type of Validator, RequiredValidator, RegularExpressionValidator, EmailValidator, and so on.
- Message – A notification message when the data is not satisfied.
- FormLoader class – This is an API client used to call the Headless Form API. The only parameter that needs to pass when initializing FormLoader is BaseUrl, which is the root link to the API endpoint; for example: http://example.com.
- FormValidator class – A class that pre-defines methods to validate data, based on Validator types, and the corresponding validation methods are called to validate the input data and return true or false values.
Form React SDK
FormContext is implemented from ReactContext to store FormState. FormState includes the following components:
- FormSubmission – Saves the values of elements when the user enters them.
- FormValidation – Saves data validation results.
- FormContainer – Saves form metadata.
React components are elements (TextboxElementBlock.tsx, TextareaElementBlock.tsx, and so on) and forms (Form.tsx, FormContainerBlock.tsx) that receive form metadata to render forms, input, select, textarea, and so on, as HTML.
FormAuthenticate
FormAuthenticate is an API client service that authenticates headless Optimizely Forms API when the form does not allow anonymous submission.
Method
- login – Function to login with the given username and password and return an access token string.
Usage
//init config option
var config = {
clientId: "name\_of\_client",
grantType: "password",
authBaseUrl: "<http://yourdomain.com/api/episerver/connect/token>
}
//get token
var formAuthenticate = new FormAuthenticate(config);
formAuthenticate.login("username", "password").then((tokenString) =\> {
//your login here
});FormCache
FormCache is a helper class that gets, sets, or removes data from sessionStorage or localStorage of a browser. The default storage is sessionStorage.
Methods
- get\<T> – Loads data items that are saved in storage.
- set\<T> – Saves data items into storage.
- remove – Removes data items that are saved in storage.
Usage
//init
var formCache = new FormCache();
//in-case you want to save to localStorage
// var formCache = new FormCache(window.localStorage);
//save data to cache
formCache.set("key", "value");
//receive data from cache
formCache.get("key");
//remove data from cache
formCache.remove("key");FormDependConditions
FormDependConditions checks conditions for an element dependent on another element. The main function checkConditions() returns a Boolean: true if all conditions are satisfied and otherwise false.
Method
- checkConditions – Determines whether an element's dependent conditions are satisfied.
Usage
//init
var formDependConditions = new FormDependConditions(formElement);
// The parameter **element** is a form element that is a child of the current **FormContainer**.
//check if satisfy the conditions
var isSatisfied = formDependConditions.checkConditions(formSubmissions);
// The parameter **formSubmissions** is an array of form element values that are inputted by user. For example: [{elementKey: "", value: ""}];FormLoader
FormLoader is an API client service that gets a form by formKey. The getForm() function returns an object of type FormContainer.
Method
- getForm – Gets a form with GUID key and returns a promise with a form.
Usage
//init
var formLoader = new FormLoader({
baseUrl: “http: //yourdomain.com/”});
//receive a form
var form = formLoader.getForm(formKey, formLanguage);
// formKey is a GUID identifier of form
// formLanguage is locale of form. For example: en, sv, …StepBuilder
StepBuilder is a helper class that arranges elements by step. The buildForm() function causes FormContainer to be an array of step that contains the elements of the step.
Method
- buildForm – Arranges elements by step and returns a form with property steps that is updated.
Usage
//init
var stepBuilder = new StepBuilder(formContainer);
// formContainer parameter is a form that was received from API.
//get form that arranged elements by step
var form = stepBuilder.buildForm();FormStorage
FormStorage is a helper class that saves, loads, or removes an array of FormSubmission from sessionStorage of a browser.
Methods
- saveFormDataToStorage – Function to save form data submission in storage.
- loadFormDataFromStorage – Function to load form data submission from storage.
- removeFormDataInStorage – Function to remove form data submission from storage.
Usage
//init
var formStorage = new FormStorage(formContainer);
//save data to storage
formStorage.saveFormDataToStorage(formSubmissions);
//load data from storage
var formSubmissions = formStorage.loadFormDataFromStorage();
//remove data from storage
formStorage.removeFormDataInStorage();FormSubmitter
FormSubmitter is an API client service class that posts a collection of FormData to headless Optimizely Forms API.
Methods
- doSubmit – Submits form data submission to the API and returns a promise resolve with an object FormSubmitResult, or a reject with an object ProblemDetail.
- doValidate – Validates form data submissions and returns the list of validation results.
Usage
//init
var formSubmitter = new FormSubmitter(formContainer, baseUrl);
//validate data before submit
var validationResult = formSubmitter.doValidate(formSubmissions);
//submit form to API
var formSubmitModel = {
formKey: formContainer.key
locale: formContainer.locale,
isFinalized: true
partialSubmissionKey: "partialSubmissionKey",
hostedPageUrl: "/",
submissionData: formSubmissions,
accessToken: "accessToken",
currentStep: 0
};
//logic to handle result
formSubmitter.doSubmit(formSubmitModel).then((result) = \ > {
//logic to handle exception
}).catch((error) = \ > {
});FormValidator
FormValidator validates the input value of the form element by validators defined in the form element's metadata. These are basic validators: RequiredValidator, EmailValidator, RegularExpressionValidator, and so on. The main function validate() returns true (valid) or false (not valid).
Methods
- validateRequired – Validate the required element.
- validateRegex – Validate the element with a RegEx pattern.
- validateFileExtension – Validate the file extension of file input.
- validateFileSize – Validate the file size of the file input.
- validateNumeric – Validate the numeric elements.
- validate – Validate the input value of the element that combines the above functions in a switch scope and returns the list of validation results.
Usage
//init
var formValidator = new FormValidator(formElement);
//validate input value
var result = formValidator.validate(value);StepDependCondition
StepDependCondition is a helper class that finds the next or previous step. If the step depends on the form element value, the class checks whether the step satisfies the dependent conditions. If it is satisfied, the step index is returned as a result. Otherwise, it attempts to find another one.
Methods
- isSatisfied – Check whether the step is satisfying the dependent condition.
- findNextStep – Recursive finding next step to display in the form.
- findPreviousStep – Find the previous step to display in the form.
- isStepValidToDisplay – Check whether the step index is valid to display.
- getInactiveStepsIndex – Get an array of inactive step indexes by dependent conditions.
Usage
//init
var stepDependCondition = new StepDependCondition(dependencyInactiveElements);
// The parameter **dependencyInactiveElements** is an array of form element keys that are inactive, since they are not satisfying the depend conditions. This parameter will need to check satisfy the depend conditions for step.
//find next step index
var nextStepIndex = stepDependCondition.findNextStep(currentStepIndex);
//find previous step index
var previousStepIndex = stepDependCondition.findPreviousStep(currentStepIndex);StepHelper
StepHelper is for step function helpers.
Methods
- isAllStepsAreNotLinked – Verify the form has all steps not attached to any page.
- isMalFormSteps – Check whether a form has steps each attached to a page.
- getCurrentStepIndex – Get the current step index depending on the current page URL.
- isInCurrentStep – Check whether the element is in step.
- getFirstInvalidElement – Get the first elementKey in the list elements that are invalid values.
- isNeedCheckDependCondition – Check whether a step is needed to check the dependent condition.
Usage
//init
var stepHelper = new StepHelper(formContainer);
//get current step index
var stepIndex = stepHelper. getCurrentStepIndex(currentPageUrl);Other util functions
- getDefaultValue – Get a default value of the element. The value can be predefinedValue, the first value of autofill data or values of items are checked.
- initFormState – Initialize FormState object based on FormContainer.
List of Models
Element base types
- FormElementBase – Base type for elements of forms.
- ValidatableElementBase – Base type for elements that can be applied with the validator.
- DataElementBlockBase – Base type of elements support validating and field-mapping to another system.
- InputElementBase – Base type for the input elements.
- SelectionBase – Base type for a selection of elements such as radios, checkboxes, dropdown, and listbox.
- ButtonBase – Base type for button-type elements.
- HiddenElementBase – Base type for hidden form elements.
Element types
- Textbox – Input and display a single line of text.
- Textarea – Input and display multiple lines of text within a defined area.
- SubmitButton – Submit the form.
- Selection – Can be rendered as Combobox or Listbox, based on SelectionBase's allowMultiSelect property.
- ResetButton – Note that the Reset button must be in a "form tag" to be functional.
- Range – Select an integer value within a specified range.
- PredefinedHidden – Hidden with a predefined value.
- ParagraphText – Rich text (with placeholder).
- Number – Input numeric values.
- ImageChoice – Select from a set of images.
- FormStep – Indicates a form step has ended.
- FileUpload – Select files to be included in a form submission.
- Choice – Can be rendered as Radio or Checkbox, based on SelectionBase's allowMultiSelect property.
- Url – Input and display a URL.
- VisitorDataHidden – Collects visitor data (IP, geo, browser, and so on) using a hidden input.
Condition type
- Condition – Determines whether the element should be displayed or hidden based on a given condition.
- ConditionProperties – Block that is displayed or hidden based on a given condition.
Enum types
- ConditionCombinationType – Combine results of all conditions satisfied.
- ConditionFunctionType – Enum represents a dependent condition operator (in the rule to evaluate dependent value).
- FormConstants – The list of constants is the keyword used for cached values.
- SatisfiedActionType – The action when the condition is satisfied.
- SubmitButtonType – Enum represents the type name of step navigation.
- ValidatorType – The list of validator types.
State types
- FormState – Type of object that is the form context.
- FormSubmission – Type of object that is form submission.
- FormValidationResult – Type of object that is form validation result.
- ElementValidationResult – Type of object that is the element validation result.
Other types
- FormContainer – The form is rendered as a hidden container.
- IdentityInfo – Type of object that is identity information.
- ProblemDetail – Type of API exception.
Related blog post
- Optimizely Headless Form Setup – Linh Hoang