Mesa Forms

Overview

Using

There are three ways to use Mesa Forms:

  1. Link to a hosted Mesa form
  2. Embed the form HTML code anywhere on the internet
  3. Build an interactive experience with the Mesa Forms JavaScript API

Overview

Building your form with the Form Builder

  1. Click on the Form Builder button from a Mesa Form Trigger to design your form in the form builder:
  2. Drag and drop field types from the right sidebar to build your form.

  3. Hover over a field and click on the pencil icon (1) to edit those field properties.  For every field you will want to customize the Label (2), which appears above your form field, and Name (3), which will be the key of the token that you will use to represent this field in the Mesa Workflow. Click the pencil icon again, or the Close button at the bottom (4) to collapse the field details.
  4. Click Save to close the Form Builder window and return to the Automations Edit page.  Be sure to save your Workflow before leaving the Automation Edit page.

Testing Mesa Form Workflows

The easiest way to test a Mesa form is to build it in the Form Builder and save your workflow.  When you add an Action to your workflow, you will see your Form tokens listed. 

If you are building your own form, or if you would like to see example values, visit your Form URL and make a test submission.  Then go back to your Automation Edit page and click the Save button to refresh your tokens.  Now you should see the examples from your last submission appear in the token selector:

Using

Hosted Mesa Forms

A hosted version of the form you build in the Mesa Form Builder is available at our Form URL from the Form Trigger in your Mesa Dashboard. 

  1. Create a workflow with a Mesa Form trigger.
  2. Click on the Open Form Builder button to design your form in the form builder:

  3. Enable your workflow and click the Save button
  4. Copy the Form URL and open it in a new tab You will see the form you designed in the From Builder.

Hosted Mesa Forms on Shopify

Your Mesa Form is also available out of the box on your Shopify site. The URL pattern is https://{{store_domain}}/apps/mesa/forms/{{workflow_key}}.  For example, the Form URL for the form in the screenshot above is https://dev-mesa.myshopify.com/apps/mesa/forms/form_contact_form. If the Shopify Customer is logged in, the payload submitted by the form will also include customer_id.  

Pre-populating Field Values from the Querystring

You can pre-populate the value of any field by setting the Value parameter in the Form Builder field settings.  Default values can also be passed via a querystring parameter that matches the field's Name property. For example, linking to the url {{form_url}}?email=bob@exmaple.com would pre-populate the email field with the value bob@exmaple.com. The success message can also be overwritten by passing the success_message querystring parameter, for example: {{form_url}}?success_message=Your+return+is+in+process.  Hosted Mesa Forms on Shopify support these same querystring parameters.

Embed the Form HTML Code

If you would rather code your form from scratch, create a form with the Form Builder and then click on the HTML Code tab (1). Click the Copy all code button (2) to select and copy all of the code to your clipboard. The form builder adds Bootstrap wrappers and classes, but feel free to make any changes you would like to your form.

If you enabled a Captcha on the Mesa Form Configuration, you will see an additional <div class="hcaptcha"></div> and a <script> tag loading an external JavaScript file. You can move these two elements around on the page, but if you delete them users will receive a Captcha error when they try to submit the form. If you disable the Captcha in the Mesa Form Configuration, you will also need to delete these elements so the Captcha does not appear on your form.

Alternatively, you can build your form from scratch.  Just add a <form> tag with method set to "POST" and an action set to your Form URL:

<form action="{{form_url}}" method="POST">
    <!-- form fields go here -->
</form>

The Mesa Forms JavaScript API

If you would like to build a more interactive form, Mesa Forms 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 JavaScript library.
  • POST {{form_url}}.json: Post a JSON object representing your form Example:
    curl 'https://dev-www.theshoppad.com/apps/mesa/forms/poulet-sauvage/form_to_email_1.json' \
  -H 'Content-Type: application/json' \
  --data-raw 'name=Bob+Biller&email=bob&message='

Here is an example of a form that is with Form Renderer and submitted via jQuery:

<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>
    </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>
$( 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) {
    console.log(data);
    $('#form-content', $form).formRender({
      formData: data
    });
    $form.fadeIn();
  });

  // Bind an AJAX POST call to the #submit button
  $('#submit', $form).bind('click', function(event) {
    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>