MODX FormIt Tutorial

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

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.

TipTip: 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.

        <form action="" method="post">

            <label for="name">Name:</label>
    
            <input type="text" name="name" id="name" >
    
            <label for="email">Email</label>
            
            <input type="text" name="email" id="email" >
    
            <label for="comment">Comment</label>
    
            <textarea name="comment" id="comment" cols="30" rows="10"></textarea>
    
            <input type="submit" value="Submit">

        </form>
    

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:

        <form action="" method="post">

            <label for="name">Name:</label>
    
            <input type="text" name="name" id="name" value="[[!+fi.name]]">
    
            <label for="email">Email</label>
            
            <input type="text" name="email" id="email" value="[[!+fi.email]]">
    
            <label for="comment">Comment</label>
    
            <textarea name="comment" id="comment" cols="30" rows="10" value="[[!+fi.comment]]"></textarea>
    
            <input type="submit" value="Submit">

        </form>
    
TipTip: 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`
    
TipTip: 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:

        <p>Name: [[+name]]</p>

        <p>Email: [[+email]]</p>

        <p>Comment: [[+comment]]</p>     
    

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

TipTip: 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]]`
    

Letís 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.

TipTip: 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.

TipTip: 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. Letís 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.

TipTip: 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.

TipTip: 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.

    <div class="well">
        <form action="[[~[[*id]]]]" method="post">

                <label for="name">Name:</label>
                <div class="controls">
                    <input type="text" name="name" value="[[!+fi.name]]" class="input-block-level">
                </div>

                <label for="email">Email:</label>
                <div class="controls">
                    <input type="text" name="email" value="[[!+fi.email]]" class="input-block-level">
                </div>

                <label for="comment">Comment:</label>
                <div class="controls">
                    <textarea name="comment" cols="30" rows="10" value="[[!+fi.comment]]" class="input-block-level"></textarea>
                </div>

            <input type="submit" value="Submit" class="btn btn-primary">

        </form>
    
    </div>

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

    <div class="well">

    <form action="[[~[[*id]]]]" method="post">
        
        <div id="name">
            <label for="name">Name:</label>
            <div class="controls">
                <input type="text" name="name" value="[[!+fi.name]]" class="input-block-level">
            </div>
        </div>

        <div id="email">
            <label for="email">Email:</label>
            <div class="controls">
                <input type="text" name="email" value="[[!+fi.email]]" class="input-block-level">
            </div>
        </div>

        <div id="comment">
            <label for="comment">Comment:</label>
            <div class="controls">
                <textarea name="comment" cols="30" rows="10" value="[[!+fi.comment]]" class="input-block-level"></textarea>
            </div>
        </div>

        <input type="submit" value="Submit" class="btn btn-primary">


    </form>
    
    </div>

Our form should look like this now.

Simple Comment Form

Now letís 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. Letís 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=`<span class="label label-important">This is a required field.</span>`]]

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:

    <div class="well">
    <form action="[[~[[*id]]]]" method="post">
        <div id="name">
            <label for="name">Name: [[!+fi.error.name:notempty=`<span class="label label-important">This is a required field.</span>`]]</label>
            <div class="controls">
                <input type="text" name="name" value="[[!+fi.name]]" class="input-block-level">
            </div>
        </div>

        <div id="email">
            <label for="email">Email: [[!+fi.error.email:notempty=`<span class="label label-important">This is a required field.</span>`]]</label>
            <div class="controls">
                <input type="text" name="email" value="[[!+fi.email]]" class="input-block-level">
            </div>
        </div>

        <div id="comment">
            <label for="comment">Comment: [[!+fi.error.comment:notempty=`<span class="label label-important">This is a required field.</span>`]]</label>
            <div class="controls">
                <textarea name="comment" cols="30" rows="10" value="[[!+fi.comment]]" class="input-block-level"></textarea>
            </div>
        </div>

        <input type="submit" value="Submit" class="btn btn-primary">


    </form>
    
    </div>

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

FormIt Field Errors

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, letís add the following code to our page.

    [[!+fi.validation_error_message:!empty=`
    <div class="alert alert-error">
      <button type="button" class="close" data-dismiss="alert">&times;</button>
      <h3>Please review the following errors:</h3>
        <ul>
            [[!+fi.error.name:!empty=`<li><a href="[[~[[*id]]]]#name">Name is a required field</a></li>`]]
            [[!+fi.error.email:!empty=`<li><a href="[[~[[*id]]]]#email">Email is a required field</a></li>`]]
            [[!+fi.error.comment:!empty=`<li><a href="[[~[[*id]]]]#comment">Comment is a required field</a></li>`]]
        </ul>
    </div>`]]

Letís 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

    <div class="alert alert-error">
      <button type="button" class="close" data-dismiss="alert">&times;</button>
      
    </div>

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

    <h3>Please review the following errors:</h3>
        <ul>
            [[!+fi.error.name:!empty=`<li><a href="[[~[[*id]]]]#name">Name is a required field</a></li>`]]
            [[!+fi.error.email:!empty=`<li><a href="[[~[[*id]]]]#email">Email is a required field</a></li>`]]
            [[!+fi.error.comment:!empty=`<li><a href="[[~[[*id]]]]#comment">Comment is a required field</a></li>`]]
        </ul>

Letís explain whatís 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=`<li><a href="[[~[[*id]]]]#name">Name is a required field</a></li>`]]

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:

FormIt Error Alert

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=`<div class="alert alert-success">
      <button type="button" class="close" data-dismiss="alert">&times;</button>
      <h3>Your comment has been submitted successfully, please check your email.</h3>
    </div>`

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

FormIt Success Message

So our final completed code should look like this:

    

<div class="container">

[[!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=`<div class="alert alert-success marginTop25">
      <button type="button" class="close" data-dismiss="alert">&times;</button>
      <h3>Your comment has been submitted successfully, please check your email.</h3>
    </div>`
    &validationErrorMessage=`<div class="alert alert-error">
      <button type="button" class="close" data-dismiss="alert">&times;</button>
      <h3>Please review the following errors:</h3>
        <ul>
            [[!+fi.error.name:!empty=`<li><a href="[[~[[*id]]]]#name">Name is a required field</a></li>`]]
            [[!+fi.error.email:!empty=`<li><a href="[[~[[*id]]]]#email">Email is a required field</a></li>`]]
            [[!+fi.error.comment:!empty=`<li><a href="[[~[[*id]]]]#comment">Comment is a required field</a></li>`]]
        </ul>
    </div>`
]]

[[!+fi.validation_error_message:!empty=`
    <div class="alert alert-error marginTop25">
      <button type="button" class="close" data-dismiss="alert">&times;</button>
      <h3>Please review the following errors:</h3>
        <ul>
            [[!+fi.error.name:!empty=`<li><a href="[[~[[*id]]]]#name">Name is a required field</a></li>`]]
            [[!+fi.error.email:!empty=`<li><a href="[[~[[*id]]]]#email">Email is a required field</a></li>`]]
            [[!+fi.error.comment:!empty=`<li><a href="[[~[[*id]]]]#comment">Comment is a required field</a></li>`]]
        </ul>
    </div>`]]
    
    [[!+fi.successMessage]]

    
<div class="well marginTop25">
    <form action="[[~[[*id]]]]" method="post">
        <div class="[[!+fi.error.name:notempty=`control-group error`]]" id="name">
            <label for="name">Name: [[!+fi.error.name:notempty=`<span class="label label-important">This is a required field.</span>`]]</label>
            <div class="controls">
                <input type="text" name="name" value="[[!+fi.name]]" class="input-block-level">
            </div>
        </div>

        <div class="[[!+fi.error.email:notempty=`control-group error`]]" id="email">
            <label for="email">Email: [[!+fi.error.email:notempty=`<span class="label label-important">This is a required field.</span>`]]</label>
            <div class="controls">
                <input type="text" name="email" value="[[!+fi.email]]" class="input-block-level">
            </div>
        </div>

        <div class="[[!+fi.error.comment:notempty=`control-group error`]]" id="comment">
            <label for="comment">Comment: [[!+fi.error.comment:notempty=`<span class="label label-important">This is a required field.</span>`]]</label>
            <div class="controls">
                <textarea name="comment" cols="30" rows="10" value="[[!+fi.comment]]" class="input-block-level"></textarea>
            </div>
        </div>

        <input type="submit" value="Submit" class="btn btn-primary">


    </form>
    
    </div>

</div>

Launch Demo

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.

21 Mar
2013

Author Benjamin Marte Category Tutorials Comments (22)

Comments (22)

  1. Wouter:
    Mar 22, 2013 at 03:41 AM

    Just in time too!
    I searched for a good tutorial, but all the tutorials I found made me want to bang my head against a wall after reading for 30 seconds.

    Then lo and behold, it shows up here! :)

  2. Martin Gartner:
    Mar 22, 2013 at 05:10 PM

    This tutorial is so cool! Thanks a lot!
    That's how I'd like to see in the official documentation...

    Eagerly awaiting your next MODx tutorial! :-)

  3. Benjamin Marte:
    Mar 22, 2013 at 05:54 PM

    Thanks for the kind words guys, I hope it proves to be useful for other MODX users.

  4. Wouter:
    Mar 25, 2013 at 04:16 AM

    I was following along this tutorial. First I followed along your tutorial "Integrating a template in Modx Revolution", then I continued with this tutorial, by integrating this tutorial into the "contact form".

    I created a new "template" folder "assets/templates/bootstrap", in which I added the bootstrap files (css, img, js). Then I had some problems getting the styling right and getting the error messages to display.

    Apparently, if you add the bootstrap styles, you have to make sure you add the styles *before* any other CSS files, or certain bootstrap CSS rules might overrule the default ones.

    After that, I got it working though.

  5. Benjamin Marte:
    Mar 25, 2013 at 05:31 PM

    @Wouter this tutorial was not meant as part of the template integration ones but this is good to know for others who might be doing the same thing as you.

    Thanks for your comments, it's great to know my tutorials are helping others.

  6. online college math courses:
    Apr 26, 2013 at 05:03 PM

    My name's Mckinley from Nunspeet, Netherlands and I have to say your article is very informative. The clarity of your post is quite good and I can trust you are an pro on this subject. With your permission, would you allow me to grab your RSS feed to keep updated with new articles? Thanks a ton and please carry on with the fantastic work.

  7. john:
    May 20, 2013 at 09:29 PM

    nice tuts! :) im looking for this kind tuts!
    please do more tuts regarding formIt without emails only form processing and saving data to database thanks :D

    great job!!

  8. Billy:
    May 28, 2013 at 08:33 AM

    Thank you very much sir. You have been great!

  9. Recoil Networks:
    Jun 07, 2013 at 06:17 PM

    Excellent tutorial but I have one question. Instead of display a "Success" alert, how can I execute Bootstraps modal window? Basically, I need to execute the JavaScript to show the modal window ('#modalWin').modal('show');. Any help is appreciated! Thank you.

  10. Benjamin Marte:
    Jun 07, 2013 at 07:47 PM

    @RecoilNetworks I would just insert the script tag with the JS code you need to execute inside the success message so in the &successMessage parameter place your JS code between the back ticks it should execute when the form has been sent successfully.

    Let me know if that doesn't work for you, good luck.

  11. Recoil Networks:
    Jun 08, 2013 at 01:14 AM

    @Benjamin Marte: Yeah, that didn't work. Any other ideas?

  12. Benjamin Marte:
    Jun 08, 2013 at 10:13 AM

    So first thing to do would be to check your JS console with Chrome of Firebug and see if you are getting any JS errors if you are getting a $ is not defined error that means your script tag is being executed before your jQuery.

    So make sure the JS to trigger the modal on the page is after your jQuery call and have the modals html as your success message.

    Before form submission the JS will trigger the modal to show but since it does not exist on the page nothing will happen, once the success message is returned FormIt places the modals html into the page and it will display.

    If that doesn't work just shoot me a link to the page and I will check it out, good luck.

  13. Recoil Networks:
    Jun 08, 2013 at 12:19 PM

    Okay, so I am very well aware of how jQuery / JavaScript works. I have Firebug installed and that was the first thing I checked was to see if I was getting a JavaScript error, which I am not. I am a little confused on what you are saying though. Why would FormIt execute the JavaScript to trigger the modal before the form submission if it is not supposed to show until after the form has been submitted? That doesn't make sense to me. The modal is on the page already. I know you know how to use Bootstrap and pretty sure that you are aware that the modal is hidden on the page so there should be no reason for FormIt to have to "place" the modal on the page. Any other help is appreciated. I'd rather not post the URL here for everyone to see though. If you have another way of getting the URL, let me know. Thank you!

  14. Benjamin Marte:
    Jun 08, 2013 at 07:24 PM

    @Recoil Networks Here check out this example I made for you view source before and after submitting the form, you need to place the modal HTML code inside your &successMessage parameter and the JS for modal show after your jQuery call.

    http://cmstricks.com/demos/formit-modal-demo

  15. @Benjamin:
    Jun 10, 2013 at 11:41 AM

    Okay, so I must be an idiot. I added the modal code to the &successMessage variable however, it is still not working. Can you email me the FormIt code you are using please? In fact, can you email me the entire page? I looked at the before and after and noticed the modal being on the page after but I am not sure how that is getting put there nor do I understand how you are opening it after the form has been submitted. I learn and understand better by seeing the actual code and since FormIt doesn't show raw code on the page, I need you to send me the raw code. I would greatly appreciate it.

    Thank you.

  16. @Benjamin:
    Jun 10, 2013 at 11:56 AM

    Nevermind, I got it working! Thank you!

  17. Benjamin Marte:
    Jun 10, 2013 at 12:16 PM

    @RecoilNetworks Glad you got it working.

  18. Aubrey Robertson:
    Jul 02, 2013 at 03:11 PM

    Great tutorial! Thanks.
    Any idea why adding the class to the span between the not_empty ticks would break the whole form? Works without the class statement - won't work with any class=""

  19. Benjamin Marte:
    Jul 02, 2013 at 03:24 PM

    Make sure your span with the class is inside the output modifier and properly closed with the back ticks (`) also make sure you use notempty instead of not_empty unless that is a typo.

  20. Aubrey Robertson:
    Jul 02, 2013 at 03:37 PM

    Thanks Benjamin. yes not_empty was a typo in the post. I copied the code exactly from the examples above. Can't paste it here. The only way I can get anything to work is without quotes (")'s between the ticks? Very strange.

  21. blogging tips:
    Jul 18, 2013 at 10:50 AM

    Keep on working, great job!

  22. Pamela:
    Jul 21, 2013 at 07:23 PM

    Thanks for the great tutorial! I was having an issue with the inputs and labels disappearing while testing the validation by submitting with empty fields. I discovered that changing the to fixes this issue.


Leave a Comment

This thread has been closed from taking new comments.

Scroll to top