Custom forms

There are many cases where you need to gather additional data from your customers on your website. This could be as part of an application process, gathering additional details on a product or even within the checkout itself.

These additional bits of information can be collected using StoreConnect’s built in Custom Form feature.

Form types

There are three types of Form that you can use with StoreConnect:

Generic forms

Think of Generic forms as a way to gather information from a customer and put this into your Salesforce org. This could be an advanced Web to Lead style form, or even a multi step application process that helps determine which product to buy. For a brief introduction to Generic Forms, see our Generic Forms video.

Checkout forms

Checkout Forms are designed to capture information relating to the entire checkout. This could be things like a Purchase Order number, or additional information about the purchaser. They are asked once per checkout and can be asked at any stage of the checkout. You can watch our Checkout Forms video to get an overview on how to use this.

Product forms

The Product Forms feature allows you to get specific information about individual products. They are collected once per product added to the cart. For example, you could ask this to get some text or an image you want to print onto a piece of clothing or perhaps the name and email of a person you are making a donation or purchase on behalf of. Our Product Forms video has a good introduction to how this works.

Using custom forms

Custom Forms gather customer input or session data during specified interaction on your website and push that data to Salesforce. These forms are built by you to collect data based on your own business requirements. Forms can be scoped to one or more stores, allowing reusability or segregation between stores. With Liquid expressions, you can enable dynamic validation and default values, ensuring that forms adapt to your specific requirements.

To create a form, start with the Form object, add one or more questions, then link it to one or more stores. For Product Forms, you must also link your form to any products for which the form is to be used.

This article covers:

• Form Architecture
• Form Configuration
• Rendering Forms

Form architecture

Custom Forms are composed of the following objects:

• Form
• Form Question
• Form Submission
• Form Answer

Form

Defines the form type and the form’s high level configuration.

There are three types of forms:

• Checkout Form - Gathers extra order or customer information during the checkout process.
• Product Form - Collect customers input related to a product when a customer adds that product to the cart.
• Generic Form - Collect data independent to any products or the checkout process and can placed anywhere on the website.

Form question

Contains the metadata for each question, including:

• The question.
• Whether an answer is required.
• Whether the question and its input are hidden from the customer.
• Validation rules.
• Data Type: Text, Text Area, Boolean, Integer, Decimal, Date, Datetime, Picklist, Multi-Picklist, or File. The multi-select option is labeled Picklist (Multi-Select) in the dropdown but stored as Multi-Picklist, which is the value to use in Liquid or through the API.
• Default Value, as a static value or a Liquid expression.
• Picklist Values, required when the data type is Picklist or Multi-Picklist.
• Whether the customer can edit their answer after checkout, from the order page.

Form submission

Completed form submitted by a customer which could be linked to an order or order product.

• Checkout Forms lookup to the order.
• Product Forms lookup to the Order Item.
• Generic Forms don’t lookup to any object but you can insert or request data that can be used to link the form to a Contact or Account, etc.

Where a Product Form is used, if the product is added to the cart multiple times with different answers each time, each unique set of answers creates a new order product. Each unique set of answers creates a separate form submission and each is related to the corresponding order product. This allows you to see what qty of a product relates to what answers.

It is likely you need the answers to be stored in a field on some other object, or perhaps you need to trigger an action depending on the answer given. Either way, you are best to build one or more Flows to manage these as you need.

Form answer

The answer to a question in the form. The Form Answer stores:

• The Form Submission this answer belongs to.
• The original question.
• The provided answer to the question.
• The data type for the answer.

Form configuration

There are many configuration options available. Not all fields require a value so only use the fields you need to achieve the desired outcome.

Form

Record Type

The form record type allows you to choose a form based on its context or purpose, and can be switched between Checkout, Generic, and Product forms.

Form Conditions

Define when and where a form should be displayed based on user interactions, specifically if during the checkout process. These conditions are written as expressions and do not need to be wrapped within Liquid braces - Neither {% ... %} or {{ ... }} are to be included. Go to the Rendering Forms section of this article for some examples.

Success Page

This is essentially a lookup for a page, either an existing one you’d like to use or a new one you can create to be used as the success page after the form is submitted.

Form question

Picklist Values

To define multiple values in a picklist, separate each option with a semicolon (;). Each value you specify will appear as a selectable item in the dropdown.

```text

Option 1;Option 2;Option 3 ```

Picklist expressions

Set Picklist Type to Expression to generate the options with Liquid instead of typing them. (Default Type works the same way for the Default Value field.)

When using expressions for picklist options, both label and value must always be specified, even if you are providing static default values.

Example:

```liquid

label: “Select a color;Red;Green;Blue” | split: “;” value: “;red;green;blue” | split: “;” ```

• label: The text shown to users in the picklist.
• value: The actual value submitted when a user selects a label.

For instance, if a user selects “Green”, the submitted value will be “green”.

You can use Liquid variables or collections to populate picklists dynamically.

Example: populating countries

```liquid

label: all_countries | map: “name” value: all_countries | map: “alpha3” ```

• all_countries: A collection of country objects.
• name: The visible name of each country.
• alpha3: The corresponding 3-letter country code (ISO Alpha-3), assuming you wish to submit the 3 char ISO code for the country.

Validation Rule

Validation rules follows this format: {validation message}: {validation condition}

• validation message - The error message shown to the user when the condition fails.
• validation condition - A condition written in Liquid syntax that determines whether the input is valid.
• Use value to refer to the submitted answer.

Example:

This rule enforces that the submitted answer is either “yes” or “no” and provided an error message to make that clear.

```liquid

You must enter ‘yes’ or ‘no’: value == “yes” or value == “no” ```

File Upload

Custom Forms support file uploads by using the File data type in a Form Question. This allows customers to upload documents, images, or other files as part of their form submission.

• The uploaded file will be saved as a URL in the corresponding Custom Form Answer’s URL field.

• File uploads submitted via the custom form are stored in your website’s CDN, and individuals with the direct link can access them.

• No record is created in the Media object that points to the asset in the CDN.

Rendering forms

Checkout forms

Displayed during the checkout process.

Display Mode

Display Mode allows you to control when a Checkout form is displayed during the purchasing process. This setting applies only to forms with the Checkout record type. The available options include:

• In Checkout: Displays the form during the checkout process at a specific step.
• After Checkout: Displays the form after the checkout process is completed.

Choosing the checkout step

Selecting “In Checkout” controls when the form appears (during checkout rather than after), but not where within the checkout flow. To control which step the form appears at, include the corresponding snippet in your checkout theme:

Checkout step	Snippet to include
Customer Information	checkout/customer_information/form
Shipping / Delivery Information	checkout/shipping_information/form
Payment Information	checkout/payment_information/additional_info
Accept Terms (Review)	checkout/accept_terms/form

You can further refine when the form appears using Conditions. See Conditions below.

Product forms

Product forms are displayed on the product page by default, before the product is added to the cart.

Submissions are saved as part of the cart’s line item and are displayed on the cart with the line item by default.

Generic forms

Generic forms can be embedded onto any page of your StoreConnect site using a little Liquid. They can also be added to content blocks the same way.

Example Code Snippet:

```liquid

{% assign custom_form = all_custom_forms[‘a0tAAAAREPLACEAAAA’] %}

{% form ‘custom-form’, identifier: custom_form.id %} {% render ‘custom_forms/questions’, questions: custom_form.questions, form: form %} {% endform %} ```

Replace a0tAAAAREPLACEAAAA with the Salesforce record ID of the form.

Conditions

A Form Condition is a Liquid expression that decides when the form appears. Write the expression on its own, with no {% ... %} or {{ ... }} wrapper.

Use current_checkout_step to pin a checkout form to one step of the checkout. It returns one of customer_information, shipping_information, payment_information, or accept_terms.

Condition	The form appears
current_checkout_step == "customer_information"	Only while the customer is entering their details
current_checkout_step == "shipping_information"	Only on the shipping step
current_checkout_step == "payment_information"	Only on the payment step
current_checkout_step == "accept_terms"	Only on the terms and conditions step

Invert any of these with != to hide the form on that step and show it everywhere else.

Combine expressions to narrow it further:

• On either the shipping or the payment step:

  ```liquid

  current_checkout_step == “shipping_information” or current_checkout_step == “payment_information” ```

• On the payment step, and only for a signed-in customer:

  ```liquid

  current_checkout_step == “payment_information” and (current_customer != nil) ```

• For any signed-in customer, at any step:

  ```liquid

  current_customer != nil ```

Important notes

Snapshotting

To maintain data integrity, form changes don’t impact existing form submissions, as answers are stored with both the question and its data type.

Hidden and uneditable fields

Check Hidden on a Form Question to capture an answer without showing the question. The field renders as <input type="hidden">, so the customer never sees it, but the value is still submitted and stored as a Form Answer. Pair it with a Default Value to record something the customer does not need to type, such as a campaign code or a value read from the session.

To show a pre-filled value the customer cannot change, use the readonly attribute in a custom question snippet in your theme, not disabled. A browser does not submit a disabled input, so the answer would be lost.

Check Editable on a Form Question to let the customer change their answer after checkout, from the order page.

In this section

• Collect customer signature at checkout
• Build an application form with payment
• Build an application form with payment - part 2