@tdcerhverv/contactform v1.0.0-alpha.8

ContactForm

Modular Contact Forms for TDC.dk open pages.

Installation

npm install @tdcerhverv/contactform

Standard Contact Form

A baseline contact form with no out-of-the-box integrations The <StandardContactForm /> is a formik-integrated modular form which should serve as the basis for all forms on TDC.dk. It is built using Material UI and Formik.

Usage

import { StandardContactForm, FormSubmission, ISubmissionState, FeedbackDialog } from '@tdcerhverv/contactform'

Props

The props for this component are defined as follows:

export interface IStandardContactForm extends IContactFormBase {
    fieldSections: IFieldSections[]
    onSubmit: FormSubmission
}

export interface IContactFormBase {
    formId: string
    optionalLabel?: string
    submitButtonDisplay?: 'RIGHT' | 'LEFT' | 'CENTER' | 'STRETCH' | 'BETWEEN'
    buttonText?: string
    buttonTextSending?: string
    alertText?: string
    modal?: IModal
    formSubmissionState: ISubmissionState | null
    setFormSubmissionState: (formSubmissionState: ISubmissionState | null) => void
    persistState: boolean
    inlineAnnouncement?: IAlert
    preFilledMessage?: string
    environment?: Environment
}

export interface IFieldSections {
    sectionTitle?: string
    fields: InputField[]
}

Required Props:

• formId is a string to identify the form
• onSubmit is a function that defines how to handle form submission. FormSubmission is a type alias for (values: unknown, formikHelpers: FormikHelpers<unknown>) => Promise<boolean>
• setFormSubmissionState is a passed down useState hook, that returns the state of the form after submission. This can be used to display any kind of feedback to the user

Optional Props:

• fieldSections is a two dimensional array which takes sections as objects. The sections include an array of fields and an optional section title (sectionTitle). Sections provide a visual distinction between groups of fields (there is 24px spacing between fields, while sections are seperated with a divider component. If you do not want multiple sections in your form, simply add 1 section which includes all inputfields.
• submitButtonDisplay allows you yo change the flexbox properties and alignment of the "send" button
• buttonText allows you to change the text in the form's submission button. Default value is "Send"
• buttonTextSending allows you the change the text in the form's submission button while the form is submitting. Default value is "Sender Besked"
• alertText allows you to change the text of the alert that is displayed when a field is not filled correctly. Default value is "Der er felter, som ikke er udfyldt korrekt"
• modal This prop task two required props. One is the close dialog handle function, and the other is the inner text for cancel button. This this props is provided, the form is now able to control the open/close state of a dialog.
• inlineAnnouncement This prop allows to have an inline Announcement at the top of the form in case any additonal information should be displayed to the user. The prop takes an object of type IAlert which can be seen below. The description can take markdown or a string.
• preFilledMessage When this is added the string will be added as initial value for the MESSAGE field.

interface IAlert {
    title: string
    description: {
        description: string
    }
    severity: 'error' | 'warning' | 'success' | 'info'
}

Optional Field Props:

• fieldWidth An optional prop that can be used to define the width of a field. if given no value, fields will default to 100% width except for number fields. The prop takes a string or an int

FormSubmission

import { StandardContactForm, FormSubmission, ISubmissionState, FeedbackDialog } from '@tdcerhverv/contactform'

const [formSubmissionState, setFormSubmissionState] = useState<ISubmissionState | null>(null)

//simple submission handler to display form values in an alert
const handleSubmission: FormSubmission = (values, _formikHelpers) => {
    alert(JSON.stringify(values, null, '\t'))
}

;<StandardContactForm formId="myForm" onSubmit={handleSubmission} setFormSubmissionState={setFormSubmissionState} />
{
    formSubmissionState && <FeedbackDialog {...formSubmissionState} />
}

Validation

The <StandardContactForm /> uses a combination of Formik and Yup to provide a standard validation schema to all forms.

Individual fields have the following validation rules and error messages:

Any fields which are not specified here are given the yup.mixed() validation rule, with the default error of Der sket en fejl. This validation should not be seen by users, but acts as a safety net for unforseen errors.

All fields can be given the required prop, which will append the yup.required() rule to that field's validation schema. Any empty fields that are required will block formik.onSubmit from being called, and display the error message 'Obligatorisk felt' as assistive text to the field.

Salesforce Form

The <SalesforceForm /> is the primary form used on TDC.dk. This form is built upon the <StandardContactForm />, and provides off-the-shelf validation and integration with our Salesforce Integration Middleware for LEAD and CASE forms.

Props

The salesforceForm has the following props:

export interface ISalesforceForm extends IContactFormProps {
    formType: FormType
    environment: Environment
    formData: ICaseForm | ILeadForm
    fields: [
        {
            salesforcemapping?: string
        } & InputField,
    ]
}

• formType prop can be CASE or LEAD, defines if this is a Case form or a Lead form.
• environment prop can be PROD or DEV, sets up to send the cases to the Salesforce production or development endpoints.
• formData prop defines all the data needed by Salesforce in addition to the fields and user-supplied values. Find the details in Salesforce Definitions section below.
• fields prop refers to input fields. Example: text, cvr, address etc.
• salesforcemapping is an optional prop, but is required for the following types of fields:
  • CHECKBOX
  • CHECKBOXGROUP
  • RADIO
  • TEXT
• Salesforce also requires a sourceUrl, though this is provided on submission as window.location.host + window.location.pathname.

interface IBaseSalesforceFormData {
    Recordtypeid?: string
    Origin: string //Origin is called LeadSource on LeadForm
}
export interface ICaseForm extends IBaseSalesforceFormData {
    Type__c: string
    Sub_Type__c: string
    Subject: string
}
export interface ILeadForm extends IBaseSalesforceFormData {
    Lead_Type__c: string
    DemandBase_Information__c?: string
}

Salesforce Definitions

CASE:

ONE+ CONFIGURATOR LEAD:

VERTIC LEAD:

Salesforce Picklist values

CASE:

Type__c:      Billing | Inquiry
Sub_Type__c:  Inquiry | Standard Inquiry
Origin:       Web - Open Pages

Vertic LEAD:

Lead_Type__c: Digital Demand Engine
LeadSource:   Web - Open Pages
Product_of_Interest__c: One+| Mobil| Internet

One+ Configurator LEAD:

Lead_Type__c: One+ Configurator
LeadSource:   Web - Open Pages
Product_of_Interest__c: One+
Product_Information__c: Its a generic field that can take any string. Max length 32000 characters.
This field contains the user choices from the One+ configurator.

FeedbackDialog

The <FeedbackDialog /> is the standalone component that can be use in conjunction with the StandardContantForm or the SaleforceForm. It take props of ISubmissionState.

Salesforce mappings

Known salesforce fields that are mapped by using the salesforcemapping parameter | field-name | field-rules | Salesforce Requirements | Business Requirements | | --------------------------- | --------------------- | :---------------------: | :-------------------: | | Web_Address__c | Text Area(255) | Optional | ✔(when the field is given) |