# Form

The **Form** tool allows you to create any kind of submission form. This makes it possible for customers to answer questions related to their order, sign up for promotions or mailing lists, or contact store departments directly such as Returns & Exchanges.

<figure><img src="/files/RHFKIsE6FMkUdjoHGyRs" alt=""><figcaption></figcaption></figure>

## Configure

### Building

Use the Form Builder to create your form from scratch. To gather the information you need, you can include headings, plain text, and various input types like text fields, dropdowns, and checkboxes.

![](/files/91ndCw5GFnvkCHrutcWB)

<figure><img src="/files/cjxoY4BbowV5KgxQe2K0" alt=""><figcaption></figcaption></figure>

### Manual Run

To preview the form, turn your workflow on and select the **Form URL** link-out icon highlighted below.

![Be sure to enable your workflow before opening the Form URL](/files/Jthj43HaxVjLrQweZJYC)

Once the workflow is enabled, complete a form and click submit to see your submission in your workflow's [Activity](https://docs.getmesa.com/workflow-activity) tab.

### Using Form variables

In later steps, use the [variable](https://docs.getmesa.com/workflow-builder/fields/variables) selector to insert a variable from your form's submission fields.

<figure><img src="/files/1ZIXnMgAfx3OfTJLJVyZ" alt=""><figcaption></figcaption></figure>

For example, if you want to send these form values to [Google Sheets](/connect/google-sheets.md), you can select the variables on the right that match the correct column in MESA.

<figure><img src="/files/9JxCTszDLH4SuVEkJPMP" alt=""><figcaption></figcaption></figure>

### Using your form

#### Linking to your form

Use the Form URL to link people to your form.

<figure><img src="/files/iMwtqjBQUIzEMazxfYFw" alt=""><figcaption></figcaption></figure>

#### Javascript embed code

You can use the embed code to embed your form anywhere you need it to appear.

<figure><img src="/files/hdSgW3X0zptLnic8vmaM" alt=""><figcaption></figcaption></figure>

### Coding your form

You can code your form from scratch using the Advanced Code snippet provided in the Form Builder if you prefer a direct coding approach.

With the Form Builder open, click the Get Code tab and copy the code from the Advanced section.

### Customizing appearance

By default, MESA adds [Bootstrap](https://getbootstrap.com/) wrappers and classes and uses its default styling. When setting up a form, MESA gives you the option to add class names to the form fields should you wish to attach custom styles.

## Going Further

### **Add to Shopify's order status page**

1\. Open the **Form** trigger and click on the copy icon on the right of the **Form Embed Code** field.

<figure><img src="/files/hdSgW3X0zptLnic8vmaM" alt=""><figcaption></figcaption></figure>

2\. From your Shopify Admin, click on **Settings** and then locate the **Checkout** settings.

3\. Scroll down until you locate the **Order status page additional scripts** section. Paste the copied Form embed code.

4\. **Save** your changes.

After saving, your form will appear on the order status page after customers place an order.

You can preview the look of the form by going to any order in your store. Click the **More Actions** dropdown and then select the **View order status page** from the drop-down menu.

### **Add a form via the Shopify theme editor**

{% hint style="info" %}
Your theme must be an [Online Store 2.0 theme](https://themes.shopify.com/themes?sort_by=most_recent\&architecture%5B%5D=os2) in order to add a MESA Form through the Shopify theme editor.
{% endhint %}

1\. Open the Form trigger and copy the entire URL to the right of the **Form URL** field.

<figure><img src="/files/iMwtqjBQUIzEMazxfYFw" alt=""><figcaption></figcaption></figure>

2\. From your Shopify Admin, click on **Online Store** under **Sales Channels**. Locate your preferred theme and click on **Customize**.

3\. In the theme editor, select a page to which you'd like to add the Form using the dropdown menu at the top.

4\. Once a page is selected, click **Add section** in the left sidebar menu. Then, scroll down to the **App** blocks and select the **MESA Form** block.

5\. Locate the **Form URL** field and paste the copied **Form embed code**. You will be able to see the Form in the theme editor as a preview after pasting the URL.

6\. **Save** your changes.

{% hint style="info" %}
After saving, you can exit the theme editor and view the form on your selected page.
{% endhint %}

### **Add to the customer account order page**

1\. Open the **Form** trigger and click on the copy icon to the right of the **Form Embed Code** field.

<figure><img src="/files/hdSgW3X0zptLnic8vmaM" alt=""><figcaption></figcaption></figure>

2\. From your Shopify Admin, click on **Online Store** under **Sales Channels**. Locate your preferred theme and click on **Actions** and then **Edit code**.

3\. Locate your theme's customer order file. Each theme varies, but a common location is under the **Templates** folder: **customers/order.liquid** file.

4\. Paste your copied **Form Embed Code** anywhere you’d like it to appear on the page.

5\. **Save** your changes. After saving, you can exit out of the theme editor and view the customer account page.

### Hosted Forms <a href="#hosted" id="hosted"></a>

Your form is also available on your Shopify site out of the box. To view your hosted form, click on the export icon under the Form URL.

{% hint style="info" %}
If your workflow is disabled, you will not be able to see your form.
{% endhint %}

<figure><img src="/files/iMwtqjBQUIzEMazxfYFw" alt=""><figcaption></figcaption></figure>

If the customer is logged in, the payload submitted by the form will also include `customer_id`.

### Styling your form

When setting up a form, MESA gives you the option to add class names to the form fields.

This HTML snippet adds a border around the form and ensures that the input fields and buttons have a border outline.

```html
<style>
 #mesa-form {
     margin-top: 25px;
     padding: 1.1428571429em;
     border: 1px solid #D9D9D9;
     border-radius: 4px;
     margin-bottom: -20px;
 }

 #mesa-form button#submit {
    border-color: #D9D9D9; 
 }
</style>
```

{% hint style="info" %}
Scripts do not apply the same styling universally and may require adjustments based on the location of the Form.&#x20;
{% endhint %}

### JavaScript API

If you would like to build something more interactive, Form has a powerful JavaScript API:

* `GET {{form_url}}.json`: (optional) retrieve your Form Builder configuration in a format that can be rendered with the [Form Renderer](https://formbuilder.online/docs/formRender/options/) JavaScript library.
* `POST {{form_url}}.json`: Post a JSON object representing your form. Example:\\

```bash
curl 'https://mymesa.site/mesa-example/forms/form_shopify_order_return.json' \
 -H 'Content-Type: application/json' \
 --data-raw 'name=Bob+Biller&email=bob&message='
```

Here is an example of a form that is built with the Form Renderer library and submitted via jQuery. To use it, simply change `{{form_url}}` in the `<form>` tag to be your MESA Form URL.

```html
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css" integrity="sha384-JcKb8q3iqJ61gNV9KGb8thSsNjpSL0n8PARn9HuZOnIxN0hoP+VmmDGMN5t9UJ0Z" crossorigin="anonymous">

<form id="mesa-form" class="container" style="display: none;" action="{{form_url}}" method="POST" name="mesa-form">
 <div id="form-content"></div>
   <div class="form-group">
     <div class="hcaptcha"></div> <!-- Remove this line to hide the captcha -->
   </div>
   <div id="error"></div>
   <div class="formbuilder-button form-group field-submit">
     <button type="submit" class="btn-primary btn" name="submit" id="submit">Submit</button>
   </div>
 </div>
</form>

<script src='https://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.3/jquery.min.js'></script>
<script src='https://cdn.jsdelivr.net/npm/formBuilder@3.4.0/dist/form-render.min.js'></script>

<script src="https://mymesa.site/forms/hcaptcha.js" async defer></script>
<script>
jQuery(document).ready(function($) {
 var $form = $('#mesa-form');
 var mesaFormUrl = $('#mesa-form').prop('action') + '.json';
 
 // Render the form from the fields configured in the MESA Dashboard Form Builder with FormRender:
 // https://formbuilder.online/docs/formRender/options/
 $.getJSON(mesaFormUrl, function(data) {
   jQuery('#form-content', $form).formRender({
     formData: data
   });

   // If this is a Shopify Checkout page, support auto-populating the customer-id field
   if (typeof Shopify !== 'undefined' && typeof Shopify.checkout !== 'undefined') {
     jQuery('#form-content input[name=customer-id]').val(Shopify.checkout.customer_id);
   }
   $form.fadeIn();
 });

 // Bind an AJAX POST call to the #submit button
 $('#submit', $form).bind('click', function(event) {
   // Validate form first, return early if fails
   if (!$form[0].checkValidity()) {
      return;
   }

   event.preventDefault();
   $(this).prop("disabled", true);

   // Post to the MESA Forms JavaScript API url, which is: "{{form_url}}.json"
   // MESA Forms will accept these Content-Types: `application/json`, `application/x-www-form-urlencoded`
   $.ajax({
     type: "POST",
     url: mesaFormUrl,
     data: $form.serializeArray(),
     success: function() {
       $('#mesa-form').html('<div class="alert alert-success" role="alert">Thank you for your submission.</div>');
     },
     error: function(jqXHR) {
       console.log(jqXHR, status, error);
       $('#error').html('<div class="alert alert-danger" role="alert">Sorry, there was an error submitting your form: ' + jqXHR.responseJSON.error.message + '. Please try again.</div>');
       $('#submit', $form).prop("disabled", false);
     }      
   }).done

 });
});
</script>
```

## Technical Notes

### **Pre-populate Field Values** <a href="#pre-populate-field-values" id="pre-populate-field-values"></a>

You can pre-populate the value of any field by setting the **Value** field in the Form Builder field settings.

Default values can also be passed via query string parameters as long as the field's **Value** has curly brackets around the same values as the field's **Name**: `{{}}`

For example:

* **Field's Name**: Email
* **Field's Value**: {{email}}

<figure><img src="/files/4UUIfGeXcJKXnHJ3e4ed" alt=""><figcaption></figcaption></figure>

Then, linking to the url `{{form_url}}?email=bob@example.com` would pre-populate the Email field with the value `bob@example.com`.

The success message can also be overwritten by passing the `success_message` query string parameter. For example: `{{form_url}}?success_message=Your+return+is+in+process.`

Hosted MESA Forms on Shopify support these same query string parameters.&#x20;

Here is an example of a field's **Value**: `{{customer.id}}`&#x20;

### **Success Redirect URL** <a href="#success-redirect-url" id="success-redirect-url"></a>

The **Success Redirect URL** field allows you to add your own redirect that displays a success message after a form is submitted.​

<figure><img src="/files/FAyupzKmJlcO0sZoiDjh" alt=""><figcaption></figcaption></figure>

### Captcha

The **Captcha** field can add a **Captcha Checkbox** to prevent unwanted spam from bots and solicitors.​

<figure><img src="/files/FAyupzKmJlcO0sZoiDjh" alt=""><figcaption></figcaption></figure>

Here's what it looks like when visiting the Form URL.

<figure><img src="/files/ZWYL9umSg7Yjao2VGYUI" alt=""><figcaption></figcaption></figure>

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.getmesa.com/tools/forms.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.