< Context / Components

Form

Introduction

A form that can be completed and submitted in the email client.

Body

submitUrl

url

End point for the form submit

formTitle

text

Title text in an <h2> tag above the form

requiredMessage

text

Text that describes required fields, this text is followed by a *. If required fields are used and no text is entered it will default to Required fields are marked with

formFields

array
A list of all the form fields, the options inside each field changed dependent on the type but each field has some common settings with the exception of hidden which only shares the type and name settings.

  • Common values for formFields

    type

    select

    Defines what type of form filed to insert. Options are: checkbox, customHTML, <!-- [date](#section-date) -->, hidden, input, radio, rating, select, swatch, textArea. Description and options for each are listed below

    layout

    select

    Selects to layout options for label, description and the element. Options are: stack - (stacks one on top of the other), inline -(places each one next to each other) column - (puts label and description in a left column and the form filed in a right column).

    label

    text

    The label of the field, for example email address

    description

    text

    A longer description, for example please enter the best email address to contact you on

    helper

    text

    Helper text appears below the form field, for example we won't share your email with anyone

    required

    boolean

    Weather this is a required field or not. Some email client will be able to validate this so empty data is not collected, but others wont so you may also want to add server side validation.

    width

    number

    A width applied to the wrapper on the form field, applied in px

    align

    select

    Selects the alignment of this section, options are: left, right, center if left blank it will inherit the alignment.

    name

    plain text

    When the form is submitted this name is associated with the value entered by the user. This is not visible on the form.

    value

    plain text

    When the form is submitted this value is associated with the name. This is not visible on the form.

  • Unique values for formFields

    These are grouped by the type value.

    checkbox

    A selectable checkbox with text that appears next to it.

    options

    array

    Each item on the array represents one checkbox

    • text

      text

      Text that appears beside the checkbox

      selected

      boolean

      Wether to preselect this checkbox

      Sample radio code

      "type":"checkbox",
      "layout":"stack",
      "label":"Check",
      "description":"Description text goes in here",
      "helper":"some advice on the element",
      "required":false,
      "width":"",
      "name":"checkbox",
      "options":[
       {
         "text":"Checkbox 1",
         "name":"name1",
         "value":"check1",
         "selected":false
       },
       {
         "text":"Checkbox 2",
         "name":"name2",
         "value":"check2",
         "selected":false
       }
      ]
      

    customHTML

    body

    html

    Used to insert custom HTML between other form fields

    type:hidden

    This is used for passing hidden information in the form, the end user doesn't see this in the email. It uses the name and value fields.

    Sample hidden code

    "type":"hidden",
    "name":"hidden",
    "value":"test"
    

    type:input

    A text input field

    variation

    select

    The type of content that will go into the input. Options are; email, number, tel, text, url.

    placeholder

    plain text

    Text that appears in place before the user enters any of their own content.

    Sample input code

    "type":"input",
    "layout":"stack",
    "label":"Text input",
    "description":"Description text goes in here",
    "helper":"some advice on the element",
    "required":true,
    "width":"",
    "name":"textinput",
    "variation":"text",
    "placeholder":"text placeholder"
    

    type:radio

    A selection of radio buttons with text that appears next to them

    options

    array

    Each item on the array represents one radio button

    • text

      text

      Text that appears beside the radio button

      value

      plain text

      When the form is submitted this value is associated with the name. This is not visible on the form.

      selected

      boolean

      Set to true if to preselect a radio button. Only one can be set to true per array.

    Sample radio code

    "type":"radio",
    "layout":"stack",
    "label":"Radio",
    "description":"Description text goes in here",
    "helper":"some advice on the element",
    "required":false,
    "width":"",
    "name":"radio",
    "options":[
      {
        "text":"Radio 1",
        "value":"radio1",
        "selected":false
      },
      {
        "text":"Radio 2",
        "value":"radio2",
        "selected":false
      }
    ]
    

    type:rating

    A rating bar either star rating or text rating.

    variation

    select

    Choose the type of rating, Options are star or text.

    fluid

    boolean

    If set to true the layout will be fluid and will adjust it's size to fill the space available.

    options

    array

    Each item on the array represents one rating value

    • text

      text

      Text value, for the rating. If the variation is set to star this is only seen as a fallback where SVG isn't supported. We recommend using something like &#9733; to replicate the SVG star with unicode. If the variation is set to text this will be the value seem in all instances.

      label

      text

      This is only used when the variation is set to star. The label text will appear below the star icon to give a description e.g. 1 star.

      value

      plain test

      When the form is submitted this value is associated with the name. This is not visible on the form.

    type:select

    Select menu used to choose a single value from an array of options.

    optionstitle

    plain text

    The default value that is shown in the select menu. e.g. please select an option

    options

    • text

      plain text

      The text of the option seen by the user

      value

      plain text

      When the form is submitted this value is associated with the name. This is not visible on the form.

    type:swatch

    Small icons to click and choose options.

    variation

    select

    Choose which type of swatch you want, options are color, image and text

    selectMultiple

    boolean

    Choose if the user can select multiple options from the array or only 1.

    options

    • color

      hex code

      Only when variation is set to color. This defines the color seen in the swatch.

      title

      plain text

      Only when variation is set to color. This is the name of the color used for accessibility.

      src

      url

      Url of the default image shown in the swatch.

      Only when variation is set to image

      srchover

      url

      Url of the image shown on hover, if this is not included then the default image will show.

      Only when variation is set to image

      srcselected

      url

      Url of the image shown when this option is selected, if this is not included then the default image will show.

      Only when variation is set to image

      alt

      plain text

      Only when variation is set to image. This is the name of the image used for accessibility.

      text

      Only when variation is set to text. The text that fills the swatch.

      value

      plain test

      When the form is submitted this value is associated with the name. This is not visible on the form.

      selected

      boolean

      Weather this option should be preselect

    type:textArea

    A textarea for the user to enter text, longer than the text input field.

    placeholder

    plain text

    Text that appears in place before the user enters any of their own content.

    maxlength

    number

    The maximum number of characters allowed in the in the textarea.

Style

style

Styling on the component container.

Example

{
  "type":"form",
  "body":{
    "id":"test1",
    "submitUrl": "http://example.com",
    "formTitle":"",
    "requiredMessage":"",
    "formFields":[
      {
        "type":"hidden",
        "name":"hidden",
        "value":"test"
      },
      {
        "type":"input",
        "layout":"stack",
        "label":"Text input",
        "description":"Description text goes in here",
        "helper":"some advice on the element",
        "required":false,
        "width":"",
        "name":"textinput",
        "variation":"text",
        "placeholder":"text placeholder"
      },
      {
        "type":"swatch",
        "layout":"stack",
        "label":"Color swatch",
        "description":"Description text goes in here",
        "helper":"some advice on the element",
        "required":false,
        "width":"",
        "name":"colorswatch",
        "variation":"color",
        "selectMultiple":false,
        "options":[
          {
            "color":"#ff0000",
            "title":"Red",
            "value":"R",
            "selected":true
          },
          {
            "color":"#00ff00",
            "title":"Green",
            "value":"G",
            "selected":false
          }
        ]
      }
    ],
    "submit":{
      "text":"submit form",
      "selected":false,
      "confirm":false,
      "confirmMessage":"Confirm you are happy to submit this data.",
      "confirmError":"Please click to confirm before submitting."
    }
  },
  "style":{
    "background": {
      "color": "#ffffff"
    },
    "margin": {
      "top": "0",
      "right": "0",
      "bottom": "0",
      "left": "0"
    },
    "padding": {
      "top": "0",
      "right": "10",
      "bottom": "0",
      "left": "10"
    },
    "border": {
      "color": "",
      "width": "",
      "style": "",
      "radius": ""
    },
    "formTitle":{
      "margin": {
        "top": "",
        "right": "",
        "bottom": "",
        "left": ""
      },
      "padding": {
        "top": "0",
        "right": "0",
        "bottom": "0",
        "left": "0"
      },
      "font": {
        "color": "",
        "decoration": "",
        "family": "",
        "style": "",
        "weight": "",
        "size": "30",
        "align": ""
      }
    },
    "requiredMessage":{
      "margin": {
        "top": "0",
        "right": "0",
        "bottom": "0",
        "left": "0"
      },
      "padding": {
        "top": "0",
        "right": "0",
        "bottom": "0",
        "left": "0"
      },
      "font": {
        "color": "",
        "decoration": "",
        "family": "",
        "style": "",
        "weight": "",
        "size": "20",
        "align": ""
      }
    },
    "label":{
      "background": {
        "color": ""
      },
      "margin": {
        "top": "10",
        "right": "0",
        "bottom": "10",
        "left": "0"
      },
      "padding": {
        "top": "",
        "right": "",
        "bottom": "",
        "left": ""
      },
      "font": {
        "color": "#000",
        "decoration": "",
        "family": "",
        "style": "",
        "weight": "",
        "size": "18",
        "align": "left"
      }
    },
    "description":{
      "margin": {
        "top": "0",
        "right": "0",
        "bottom": "0",
        "left": "0"
      },
      "font": {
        "color": "",
        "decoration": "",
        "family": "",
        "style": "",
        "weight": "",
        "size": "16",
        "align": ""
      }
    },
    "helper":{
      "margin": {
        "top": "0",
        "right": "0",
        "bottom": "0",
        "left": "0"
      },
      "font": {
        "color": "",
        "decoration": "",
        "family": "",
        "style": "",
        "weight": "",
        "size": "12",
        "align": ""
      }
    },
    "required":{
      "font":{
        "color":"#ff2020",
        "size":"20"
      }
    },
    "input":{
      "background": {
        "color": ""
      },
      "margin": {
        "top": "0",
        "right": "0",
        "bottom": "0",
        "left": "0"
      },
      "padding": {
        "top": "5",
        "right": "5",
        "bottom": "5",
        "left": "5"
      },
      "border": {
        "color": "#d7d7d7",
        "width": "1",
        "style": "solid",
        "radius": ""
      },
      "font": {
        "color": "",
        "decoration": "",
        "family": "",
        "style": "",
        "weight": "",
        "size": "16",
        "align": "left"
      },
      "placeholder":{
        "font": {
          "color": "",
          "decoration": "",
          "family": "",
          "style": "",
          "weight": "",
          "size": "",
          "align": ""
        }
      }
    },
    "colorSwatch":{
      "height":"60",
      "width":"60",
      "margin": {
        "top": "5",
        "right": "5",
        "bottom": "5",
        "left": "5"
      },
      "padding": {
        "top": "5",
        "right": "5",
        "bottom": "5",
        "left": "5"
      },
      "border": {
        "color": "#d7d7d7",
        "width": "2",
        "style": "solid",
        "radius": ""
      },
      "hover":{
        "margin": {
          "top": "",
          "right": "",
          "bottom": "",
          "left": ""
        },
        "padding": {
          "top": "",
          "right": "",
          "bottom": "",
          "left": ""
        },
        "border": {
          "color": "#333",
          "width": "2",
          "style": "solid",
          "radius": ""
        }
      },
      "selected":{
        "margin": {
          "top": "",
          "right": "",
          "bottom": "",
          "left": ""
        },
        "padding": {
          "top": "",
          "right": "",
          "bottom": "",
          "left": ""
        },
        "border": {
          "color": "#f69513",
          "width": "2",
          "style": "solid",
          "radius": ""
        }
      }
    },
    "submitWrapper":{
      "background": {
        "color": ""
      },
      "margin": {
        "top": "",
        "right": "",
        "bottom": "",
        "left": ""
      },
      "padding": {
        "top": "10",
        "right": "10",
        "bottom": "10",
        "left": "10"
      },
      "border": {
        "color": "",
        "width": "",
        "style": "",
        "radius": ""
      },
      "boxShadow": {
        "horizontalOffset": "",
        "verticalOffset": "",
        "blur": "",
        "spread": "",
        "color": ""
      },
      "font": {
        "color": "",
        "decoration": "",
        "family": "",
        "style": "",
        "weight": "",
        "size": "",
        "align": "center"
      }
    },
    "submit":{
      "height":"50",
      "width":"300",
      "background": {
        "color": "#333"
      },
      "margin": {
        "top": "",
        "right": "",
        "bottom": "",
        "left": ""
      },
      "border": {
        "color": "transparent",
        "width": "0",
        "style": "solid",
        "radius": ""
      },
      "boxShadow": {
        "horizontalOffset": "",
        "verticalOffset": "",
        "blur": "",
        "spread": "",
        "color": ""
      },
      "font": {
        "color": "#fff",
        "decoration": "",
        "family": "",
        "style": "",
        "weight": "",
        "size": "16",
        "align": "center"
      },
      "hover":{
        "background": {
          "color": ""
        },
        "margin": {
          "top": "",
          "right": "",
          "bottom": "",
          "left": ""
        },
        "border": {
          "color": "",
          "width": "",
          "style": "",
          "radius": ""
        },
        "boxShadow": {
          "horizontalOffset": "",
          "verticalOffset": "",
          "blur": "",
          "spread": "",
          "color": ""
        },
        "font": {
          "color": "#f69513",
          "decoration": "",
          "family": "",
          "style": "",
          "weight": "",
          "size": "",
          "align": ""
        }
      }
    },
    "submitConfirmMessage":{
      "font": {
        "color": "",
        "decoration": "",
        "family": "",
        "style": "",
        "weight": "",
        "size": "",
        "align": "center"
      }
    },
    "submitConfirmError":{
      "font": {
        "color": "#ff6666",
        "decoration": "",
        "family": "",
        "style": "",
        "weight": "",
        "size": "14",
        "align": "center"
      }
    },
    "submitConfirmCheckbox":{
      "height":"25",
      "width":"25",
      "background": {
        "color": "#eee",
        "image":""
      },
      "margin": {
        "top": "0",
        "right": "10",
        "bottom": "0",
        "left": "0"
      },
      "padding": {
        "top": "4",
        "right": "4",
        "bottom": "4",
        "left": "4"
      },
      "border": {
        "color": "#eee",
        "width": "1",
        "style": "solid",
        "radius": ""
      },
      "hover":{
        "background": {
          "color": "",
          "image":""
        },
        "margin": {
          "top": "",
          "right": "",
          "bottom": "",
          "left": ""
        },
        "padding": {
          "top": "",
          "right": "",
          "bottom": "",
          "left": ""
        },
        "border": {
          "color": "",
          "width": "",
          "style": "",
          "radius": ""
        }
      },
      "selected":{
        "background": {
          "color": "#92d59e",
          "image":""
        },
        "margin": {
          "top": "",
          "right": "",
          "bottom": "",
          "left": ""
        },
        "padding": {
          "top": "",
          "right": "",
          "bottom": "",
          "left": ""
        },
        "border": {
          "color": "",
          "width": "",
          "style": "",
          "radius": ""
        }
      }
    }
  }
}