FormLogic

README.md

Form Logic

Documentation about all Form Logic features.

MultiStepsForm

Handles all the logic for managing a multi step form that is implemented using the native Tabs component from Webflow.

Parameters

form

• element: Element or selector of the form.
• phoneLocale: Custom validation for phone locales.
• invalidErrorMessage: Defines a generic error message when some fields are missing.
• scrollTopOnChange: Defines if the viewport should scroll up when changing steps. Accepts boolean | "page" | "form".
• hideOnSuccess: Defines if the form should be hidden when it's submitted successfully.

nextButton, backButton

Defines the button element's settings.

• element: Element or selector of the button.
• buttonText: Allows to update the button's text based on the current step the user is on. Accepts an array of:

{
  step: number;
  text: string;
}

errorBlock, succesBlock, loader

Defines the element that will display all errors, success messages or a loader.

• element: Element or CSS selector.
• displayProperty: Defines the CSS property to display the element.
• noTransition: If set to true, the element will be straitgh showed / hidden without any transition.

tabs

Defines the Tabs component element inside the form. Form Logic automatically detects it, but you might want to manually define the element in case there are mutliple Tabs components.

• element: Element or CSS selector.

navButtons

Defines navigation buttons for specific steps.

• selector: CSS selector for the nav button.
• stepTargets: The targets of the button. If more than one target is provided, the button will receive the "active" CSS class when any of the steps is reached, and the "completed" class when the last of them is reached.

fields

Extra custom information for form fields. Accepts an Array of:

• name: The form field name.
• customValidator: A custom callback to check if a form is valid. It must return a boolean value.
• invalidError: Defines a custom error to display when the field is not valid.

Methods

MultiStepsForm.disableStep(stepIndex: number)

Disables a step. When disabling a step

MultiStepsForm.displayLoader()

Displays the loader. The form is disabled while the loader is displayed.

MultiStepsForm.hideLoader()

Hides the loader. The form is re-enabled.

MultiStepsForm.displayError(message?: string)

Displays the error block.

MultiStepsForm.hideError()

Hides the error block.

MultiStepsForm.setCurrentStep: (step: number)

Moves the user to a new step.

MultiStepsForm.getStepInstance: (stepIndex?: number | undefined) => Step

Returns a Step instance. If a step index is provided, it will return that step's instance. If not, it will return the current step instance where the user is located.

MultiStepsForm.requestStepChange: (targetStep: number | "next" | "back")

Programmatically requests a step change on the user behalf. It simulates the user clicking Next/Back/Navigation.

MultiStepsForm.conclude()

Disables the form. After concluding, the user can't use the Next/Back/Navigation buttons.

MultiStepsForm.on(event: string, callback: (detail) => void)

Using an Observer Pattern, MultiStepsForm provides some internal events to handle logic.

availabilitychange

Is triggered when a step is enabled/disabled. The callback provides:

(detail: {
  stepIndex: number;
  isDisabled: boolean;
}) => void;

stepchange

Defines when a step was changed into view. The callback provides:

(newStep: number) => void;

validitychange

Defines when a step changes its validity (all form fields inside the step are validly filled). The callback provides:

(detail: {
  stepIndex: number;
  isValid: boolean;
}) => void;

stepchangerequest

This event is fired when the user clicks on a navigation button (Next or a specific step button) to navigate to it. It will only be fired if the step is valid. This event allows to run logic before switching steps. The callback provides:

(detail: {
    currentStep: number;
    targetStep: number;
}) => void;

input

This event is fired whenever the user inputs data.

The callback provides:

(fieldData: FieldData) => void;

error

This event is fired whenever an error is displayed to the user.

The callback provides:

(error: string) => void;

Step

Properties

Step.element

Defines the Tab Pane element that belongs to the step.

Step.stepIndex

Defines the index of the step.

Step.fieldsStore

Holds the FormLogic Fields store.

Methods

Step.getFieldsData(name?: string)

Returns a FieldData object of a specific field (if the name is provided) or all fields. If no name is provided, it returns an Array with all the field's data.

Step.getFieldsValue(name?: string)

Returns the current value of a specific field (if the name is provided) or all fields.

If no name is provided, all fields are returned like this:

Record<fieldName, fieldValue>

// Example:
const allFieldsData = {
  name: 'Alex',
  email: 'alexiglesias@finsweet.com',
  purchaseDate: '2020-05-01',
}

Step.getFieldsElements(name?: string)

Returns the FieldData.elements property of a specific field (if the name is provided) or all fields.

If no name is provided, all fields are returned like this:

Record<fieldName, elements>

// Example:
const allFieldsElements = {
  name: [...],
  email: [...],
  purchaseDate: [...],
}

Step.on(event: string, callback: (detail) => void)

Allows running callbacks on specific events fired by the step instance.

input

This event is fired whenever the user inputs data in the step.

The callback provides:

(fieldData: FieldData) => void;

error

This event is fired whenever an error is displayed to the user in the step.

The callback provides:

(error: string) => void;

FieldData

Properties

FieldData.name

Defines the name of the field.

FieldData.step

Defines the step index where the fields is located.

FieldData.elements

Contains an array with all the elements that match the field name.

FieldData.invalidError

Defines the error to display to the user if the field is not valid.

FieldData.value

Holds the current value of the field.

Methods

FieldData.isValid()

Returns a boolean with the validness of the field.