Markup Factory Documentation

Form Builder

The form builder is currently in Beta. Let us know if you would like to use it.

Overview of the Form Builder

The Markup Factory form builder allows you to publish forms on your website that perform a variety of actions.  A web form can be inserted on any Page, Template, or Snippet within your website. The same form may also be displayed in multiple locations on your website if necessary. You can create multiple unique forms for various needs.

Forms can be used for a variety of functions including:

• A contact form which sends an email to a specified address
  
• Sign up form
• Surveys
• Online application forms
• Online payment forms

Markup Factory has a built-in form processing engine that processes data submitted through forms created using the Markup Factory form builder. The form processing engine features a number of processing actions that can be configured using the format described below.

A basic understanding of HTML forms is required to use this module. To learn more about this topic, visit W3Schools.

Form Configuration

To create a form, you'll need to create both a form configuration file and an accompanying CSS style sheet. The form configuration file includes all of the fields, notes, actions, and other items that will be included on your form. The CSS style sheet controls the visual display of the form.

The configuration file needs to follow the JSON format described below.

Form Object Properties

• name: (String) The name of the form
• id: (String) The HTML id
• actions: (Array) A list of actions to execute
• errormessage: (String) The error message that will displayed when the form is submitted with errors
• classes: (String) CSS classes to apply to the form tag
• submit: (String) The text on the submit button.
• items: (Array) The form items

Fields

Common Field Properties

These properties can be applied to most form items (values in square brackets, [], are the defaults:

• name: (String) [field] The name of the element
• label: (String) [name, capitalized] the item label
• type: (String) [text] the field
• hint: (String) Helpful text to display when the element is hovered over with the mouse
• wrapelement: (String) [div] The element "wrapping" the form item
• classes: (String) CSS classes applied to the element itself
• wrapclasses: (String) CSS classes applied to the "wrap" element
• required: (boolean) [false] Is input required for this field? (see Validation)
• validates: Validation actions (see Validation)

The Markup Factory Form Builder supports most of the standard field types. Additional properties that can be applied to them are listed here:

• fieldset: A group of fields.
  • items: (Array) Fields to place within the fieldset
  • legend: (String) The fieldset legend
• text: A normal text input field
• checkbox
  • checked: (boolean) Is the checkbox checked?
• radiogroup: A group of radio buttons. This behaves like a fieldset, but the items are radio buttons, and only need to have the name and/or value specified:

          
  ...        
  {          
    "name" : "yesorno",          
    "type" : "radiogroup",          
    "legend" : "Answer Yes or No",          
    "items" : [            
      {              
        "label" : "Yes",              
        "value" : "yes",              
        "checked" : true            
      },            
      {              
        "label" : "No",              
        "value" : "no"            
      }          
    ]        
  },        
  ...      
  

• select: A drop-down select list. The items Array works the same way as a radiogroup, but the Boolean value "selected" is used instead of "checked"
• textarea
  • rows: (Number) [24] The number of rows shown
  • cols: (Number) [80] The number of columns shown
• hidden: These fields will not be displayed, but they are useful for for sending extra values along with a form submission

Non-form Items

Other non-form items you can put on your form are:

• heading: Heading text
• note: Some text for explanation

They both allow the following properties:

• name: The text to display
• tag: The HTML tag used (the defaults are H3 for "heading" and P for "note")
• classes: CSS classes
• id: The HTML ID

Actions

Actions are functions that are performed after your form is submitted. The following actions are available to attach to your form configuration file. If you include multiple actions for the form they will be executed sequentially.

• mail: By default, the "mail" action will send an email detailing the the fields and their contents to the Administrator Email defined in the Markup Factory Installation Settings. To use the action with no parameters, simply supply "mail" as one of the elements of the "actions" Array. You can also pass parameters to the mail action like this:

  
  ...        
  "actions" : [          
    { "mail" :             
      {              
        "to" : "[email protected]",              
        "subject" : "I Just filled out your form",              
        "from" : "[email protected]"            
      }          
    },          
    ...        
  ], 
  ...      
  

  Supported parameters are "to", "subject", and "from".
  • from: This is the email address that will appear as the sender when the message is sent. if no from option is supplied the following will be tried (in order):
    • The contents of any field named email if one is present
    • The to address if one was supplied in the options.
• redirect: The "redirect" action lets you redirect the user to another page when they are finished submitting a form and the system is finished processing. It is typically specified as the last action. It takes the page that you want to redirect to as its argument. Use it like this:

          
  ...        
    "actions" : [          
      ...          
      { "redirect" : "/contact/thankyou" }        
    ],        
  ...      
  

  If the String "redirect" is supplied with no arguments, the user will be redirected to the home page (i.e., http://example.com/)
• message: The "redirect" action returns a string that was specified as the argument to the action and prints that string on the screen after the form is submitted if the action was the final action in the list:

  
  ...        
    "actions" : [          
      ...          
      { "message" : "Thank you for submitting my form!" }        
    ],        
  ...      
  

Validation

Validation is essential when building useful and functional web forms. The Markup Factory form builder makes validation easy by providing automatic server-side validation for any fields that you designate. The error message is customizable through the form configuration file. The "required" and "validates" properties of applicable fields determine how the validation will be applied.

Required

Any form item with the "required" : true property will not pass validation unless the field has something in it.

Validates

The "validates" property takes a space-separated String list of validation actions to perform on the field. The list is fairly self-explanatory:

• number
• digits
• email
• uscanzip
• usstate
• usphone
• creditcard
• ssn
• alpha
• alphanum
• date

For example, to make sure you field only contains letters and numbers, add the "validates" : "alphanum" property to the field definition. Multiple validations can be used for a single field by separating them with spaces, but this is rarely useful.

Sample Contact Form

The code below will create a simple contact form that will generate an email sent out to the address specified in the configuration file. The data from the form will also be included in the notification email. Feel free to copy this code and revise it to your likings.

Configuration File Code

File Name: /assets/handle/request.form.json

Form Definition:

  
{    
  "name": "request",     
  "actions": [       
    { "mail" : { "to" : "[email protected]" } }    
  ],     
  "submit" : "Send my request",    
  "items": [      
    {        
      "name": "requesttype",         
      "label": "Request Type",         
      "type": "select",         
      "items": [          
        {            
          "value": "general",             
          "name": "I have a general question."          
        },           
        { 
          "value": "update",             
          "name": "I would like a status update"          
        }        
      ]      
    },       
    {         
      "name": "name"      
    },       
    {        
      "name": "phone",         
      "validates": "usphone"      
    },       
    {        
      "name": "email",         
      "validates": "email",         
      "required": true      
    },       
    {        
      "name": "notes",         
      "type": "textarea",         
      "cols": 40,         
      "rows": 6      
    }    
  ]  
}  

Example output: (this form has been disabled and is for demonstration purposes only)

Markup Factory Function Call

Upload the form definition to your Files. Before you do this, it is a good idea to run your form definition through a tool such as JSONLint to verify that it is formatted correctly.

Insert this MFScript tag into your Template, Snippet, or Page at the place where you would like your form to appear.

{{Form File="/assets/handle/request.form.json"}}

Complex Forms

It is possible to create fairly complex forms using the Markup Factory Form Builder. The more fields you add, the longer the form will be. Special care should be taken to verify that all of the fields included on your web form are actually necessary for the benefit of your visitors. The longer and more complex your forms are, the less apt website visitors will be to use them. It is good practice to keep forms short and sweet and to keep the number of fields to the absolute minimum.