MODX FormIt Tutorial

In this tutorial we will discuss how to create a form in MODX with FormIt, how to display individual error messages for input fields, an error message alert box with a list of errors and a success message. Let's get started we got a lot to cover.

Prerequisites

• FormIt Extra
• Bootstrap Framework (if you want to style your form like our example)

What is FormIt?

FormIt is a dynamic form processing Snippet for MODX Revolution. It handles a form after submission, performing validation and follow-up actions like sending an email. It does not generate the form, but it can repopulate it if it fails validation.

Basically FormIt is a simple MODX Extra that handles what occurs before and after it interacts with a form on your MODX site. For more information about how FormIt works and what other features and options it has please refer to the official FormIt documentation.

Tip: Using FormIt is not necessary, you can also create your own form and PHP code to validate and process your form without the use of FormIt.

FormIt works just like any other MODX extra you call the snippet and pass some parameters, FormIt also comes with built in Hooks. Hooks are basically scripts that run during FormIt processing. Hooks can be chained; the first hook will execute, and if it succeeds, it will proceed onto the next hook.

FormIt also has Pre-Hooks which execute before you load your form; a good example of a Pre-Hook is one which sets a default value to your forms input fields for older browsers that don't support the input placeholder parameter.

You can create your own custom Hook and Pre-Hooks and call these in the preHook and hook parameters of FormIt, remember these will be executed based on the order in which they are in your hook or pre-hook call so if one hook fails it will stop and not execute the next one.

For more information on hooks and pre-hooks, see the Hooks on the MODX RTFM page.

Creating your forms HTML

The first step is to create the HTML for your form, for this example we will create a simple comment form that will have 3 fields that our user will fill out which are: Name, Email and Comment. Here is what our forms HTML looks like.

  

      Name:
      
      Email
      
      Comment
      
      
  

Adding Placeholder Tags

In order to retrieve the values of our form with FormIt we need to add placeholders to our input fields so FormIt knows how to process them. All FormIt placeholders must be prefixed with fi so FormIt knows it's a placeholder which pertains to it, so after doing this our forms HTML code should look like this:

    

        Name:
        
        Email
        
        Comment
        
        
    

Tip: The default FormIt placeholder prefix is fi but this is not mandatory, you can specify your own custom placeholder prefix by adding the placeholderPrefix property to your FormIt call.

As you can see we are calling our placeholders uncached by using the (!) to make sure we don't receive cached values from previous form entries followed by a (+) which is the placeholder syntax for MODX internal tag system. It is good practice to use the name or ID of your input field as your placeholder in order to keep things relevant but this is not a requirement.

Adding the FormIt Call

So far we have modified our HTML form by adding placeholders to the input fields so FormIt knows where to get the values from, now we have to add our FormIt call which looks something like this:

[[!FormIt?
  &hooks=`email`
  &emailFrom=`donotreply[@]yourdomain.com`
  &emailTpl=`myEmailChunk`
  &emailTo=`[[+email]]`
  &emailSubject=`My First FormIt Form`
]]

First we are instantiating the FormIt snippet by calling it uncached

  [[!FormIt]]

The (?) lets the snippet know that we are about to send it some parameters or set some properties. The first parameter we are passing is the email hook.

  &hooks=`email`

Tip: To view all of the email hook properties that can be accessed please refer to the email properties page.

Now that we've instantiated the email hook we can access its properties. The first one is the emailFrom property.

  &emailFrom=`donotreply[@]yourdomain.com`

This property allows us to specify the email sender that will appear on our forms email response. The next property is emailTpl.

  &emailTpl=`myEmailChunk`

This property allows us to specify the name of the chunk we will use to format the outgoing email we will submit to our recipient; this is the sample code we are using inside the myEmailChunk:

  
Name: [[+name]]
  
Email: [[+email]]
  
Comment: [[+comment]]

As you can see all our chunk contains is some HTML code and the placeholder for our FormIt input fields.

Tip: Remember the emailTpl can contain images and HTML code; just make sure your image paths are absolute so they can be viewed on the recipients email client.

The emailTo property:

  &emailTo=`[[+email]]`

Lets us specify a who will receive the form when its submitted, in this case we are using the email placeholder since we want the user filling out the form to receive the email.

Tip: You can specify more than one email recipient in the emailTo property just make sure you insert a (,) after each email address.

The last property:

  &emailSubject=`My First FormIt Form`

Let's us insert a predefined email subject for our form.

Tip: You can also use an input field and use the placeholder as the value for this property in order to allow the user to specify a custom subject, in that case your emailSubject property would look something like this:

    &emailSubject=`[[+subject]]`
  

Validation

The next step is to add validation to our form so we can make sure each input field is filled out before submitting the form. In order to achieve this we just need to add the validate parameter to our FormIt call and specify which fields are required in order to submit the form successfully. Lets add our validate parameter and make our name, email and comment fields required.

  &validate=`name:required,
    email:email:required,
    comment:required:stripTags`

You may be asking yourself how do I tell FormIt which field it needs to check, easy you use the input fields name attribute and put a (:required) after it and FormIt automatically knows that this is a required field.

The validate parameter can be chained in order to validate more than one field, each field value needs to be separated by a (,) and FormIt will take care of the rest.

Tip: If you notice the email field has email: twice this is not a typo this is how FormIt validates required email fields, so keep this in mind.

Adding Validation Errors and Styling our Form

So we just made our fields required no we need to make user friendly error messages so our users know that there are errors they need to correct before they can successfully submit the form. Before we do that we will need to modify our HTML structure in order to take advantage of twitter Bootstraps styles.

Tip: Make sure your HTML template has references to Bootstraps classes and js files.

In order to use Bootstraps validation states we need to wrap our inputs with a div that has the controls class.

      

      

        Name:
        

            
        
        Email:
        

            
        
        Comment:
        

            
        
        
    
  

Now let's wrap our labels and divs with the control class with a div with an ID attribute for each of these.

  

    

        

            Name:
            

                
            
        
        

            Email:
            

                
            
        
        

            Comment:
            

                
            
        
        
    
  

Our form should look like this now.

Now lets start adding the FormIt error messages to our form, we will be displaying our error messages next to our field labels. Validation errors are prefixed with fi.error.placeholder_name then you can use and Output Modifier in order to check if the message should display. Lets add this line of code next to all of our label tags; this is where our error messages will appear.

    [[!+fi.error.placeholder_name:notempty=`This is a required field.`]]

What this does is call the FormIt error processor uncached we need to replace placeholder_name with the name of the placeholder we used for the input field the error message is referring to, then we use the Output Modifier notempty this tells MODX to display the value of this error placeholder when there is an error for the specific input. Now our forms HTML should look something like this:

  

    

        

            Name: [[!+fi.error.name:notempty=`This is a required field.`]]
            

                
            
        
        

            Email: [[!+fi.error.email:notempty=`This is a required field.`]]
            

                
            
        
        

            Comment: [[!+fi.error.comment:notempty=`This is a required field.`]]
            

                
            
        
        
    
  

If you submit the form with all fields empty you should now see error messages next to the field labels.

Adding Error Alert Messages

So we already added field validation errors now let's go the extra mile for a great user experience and let's add an error alert box that will list all the errors in our form. FormIt has a validation_error_message placeholder that will allow us to do this, lets add the following code to our page.

  [[!+fi.validation_error_message:!empty=`
    

      ×
      
Please review the following errors:
        

            [[!+fi.error.name:!empty=`
Name is a required field
`]]
            [[!+fi.error.email:!empty=`
Email is a required field
`]]
            [[!+fi.error.comment:!empty=`
Comment is a required field
`]]
        
    
`]]

Lets go through our code to see what is happening, first we are calling the validation_error_message uncached and we're telling it to display our HTML if there are validation errors

  [[!+fi.validation_error_message:!empty=``]]

Then we insert the Bootstrap code for the error alert message box

  

    ×
  

Next we insert an h3 title with a message and an unordered list that will display the errors in our form.

  
Please review the following errors:
    

        [[!+fi.error.name:!empty=`
Name is a required field
`]]
        [[!+fi.error.email:!empty=`
Email is a required field
`]]
        [[!+fi.error.comment:!empty=`
Comment is a required field
`]]
    

Lets explain whats going on here, we are using the same principle we used for our input validation errors. You can see we are using the validation error place holder with the name of each of our input fields and telling it to display a list item with a link and an error message for each of our errors.

  [[!+fi.error.name:!empty=`
Name is a required field
`]]

If you look at the href of our link you will notice a MODX tag before the Anchor ID of each error.

  href="[[~[[*id]]]]#name"

This will ensure that when you click on the link of the error message the page will scroll down to the Anchor ID we used in each of our forms sections.

So if you submit the form with an empty field you will see something like this:

Adding a Success Message

We will use FormIts successMessage property in order to display a user friendly message to our user which will let them know we have received their form submission successfully. The successMessage parameter accepts HTML or a simple message as its value in this example we will be using HTML since we will be using Bootstrap to style our success message. Let's add the successMessage parameter with our HTML code to our FormIt call.

  &successMessage=`

    ×
    
Your comment has been submitted successfully, please check your email.
  
`

Now when the form is submitted successfully without any errors our users will see this message.

So our final completed code should look like this:

  

[[!FormIt?
   &hooks=`email`
   &emailFrom=`donotreply[@]youremail.com`
   &emailTpl=`MyEmailChunk`
   &emailTo=`[[+email]]`
   &emailSubject=`Your Subject Goes Here`
   &validate=`name:required,
      email:email:required,
      comment:required:stripTags`
      &successMessage=`

      ×
      
Your comment has been submitted successfully, please check your email.
    
`
    &validationErrorMessage=`

      ×
      
Please review the following errors:
        

            [[!+fi.error.name:!empty=`
Name is a required field
`]]
            [[!+fi.error.email:!empty=`
Email is a required field
`]]
            [[!+fi.error.comment:!empty=`
Comment is a required field
`]]
        
    
`
]]
[[!+fi.validation_error_message:!empty=`
    

      ×
      
Please review the following errors:
        

            [[!+fi.error.name:!empty=`
Name is a required field
`]]
            [[!+fi.error.email:!empty=`
Email is a required field
`]]
            [[!+fi.error.comment:!empty=`
Comment is a required field
`]]
        
    
`]]
    [[!+fi.successMessage]]

    

        

            Name: [[!+fi.error.name:notempty=`This is a required field.`]]
            

                
            
        
        

            Email: [[!+fi.error.email:notempty=`This is a required field.`]]
            

                
            
        
        

            Comment: [[!+fi.error.comment:notempty=`This is a required field.`]]
            

                
            
        
        
    
  

This concludes our FormIt tutorial I hope you learned something new or got a better understanding on how FormIt works, let me know your feedback and don't forget you can use the contact form to suggest a tutorial you would like us to cover or why not make your own tutorial as a guest blogger on our site. Thanks and see you next time.