Walkthrough on formit

I have seen the documentation but I am still having trouble understanding what I need to do. If anyone knows some helpful getting started documentation I would appreciate it. Thank you

In short, you have to add a call to the FormIt snippet and a normal HTML form to your page.


Here is a basic example: (This form actually does nothing at all.)

[[!FormIt?
   &hooks=``
   &validate=`myfield:required`
   &successMessage=`Successfully sent!`
]]

[[!+fi.successMessage]]
[[!+fi.validation_error_message]]

<form id="myform" action="[[~[[*id]]]]" method="post">   
   <div>
       [[!+fi.error.myfield]]
       <label for="myfield">my Field</label>
       <input type="text" name="myfield" value="[[!+fi.myfield]]">
   </div>
   <input type="submit" value="Send">
</form>
  • When you click the “Send” button, the form data is sent to the same page action="[[~[[*id]]]]"
  • The FormIt snippet gets executed
    1. The snippet checks if a form has been sent (is $_POST empty?)
    2. The snippet validates the sent data (is “myfield” not empty? &validate=`myfield:required`)
    3. If the validation is successful, the hooks specified in the property &hooks are executed.
    4. If all hooks are successfully executed, the placeholder [[!+fi.successMessage]] is filled with the defined success message (&successMessage).
  • If the form validation fails, the placeholder for the general validation error message [[!+fi.validation_error_message]] is filled, as well as the placeholder for the specific field error message [[!+fi.error.myfield]].

An example of a more useful form, that sends an email and redirects:

[[!FormIt?
   &hooks=`email,redirect`
   &validate=`myfield:required`
   &redirectTo=`1`
   &emailTpl=`myEmailTemplate`
   &emailSubject=`Test Mail`
   &emailTo=`you@yourdomain.com`
   &emailHtml=`0`
   &submitVar=`mySubmit`
]]

<form id="myform" action="[[~[[*id]]]]" method="post">   
   <div>
       [[!+fi.error.myfield]]
       <label for="myfield">my Field</label>
       <input type="text" name="myfield" value="[[!+fi.myfield]]">
   </div>
   <input type="submit" name="mySubmit" value="Send">
</form>
  • &hooks=`email,redirect` → After validation, FormIt first sends an email, then redirects to another page (if the email was sent successfully).
  • &redirectTo → the page to redirect to. Used by the redirect hook
  • &emailTpl, &emailSubject, &emailTo, etc. → different properties for the email hook. (In the chunk “myEmailTemplate” you can use placeholders like [[+myfield]] for the form field values.)
  • &submitVar → must correspond to the “name” attribute of the “Send” button, if there are multiple forms on the page.
1 Like

So I copied and pasted the second chunk and used it on my page. I changed the email address but the form isn’t being sent to my email. Any suggestions? Sorry it has been a few years since I have studied this stuff.

Have you set up your site for sending email? If not, here are the docs (I highly recommend using SMTP and not the PHP mail() function):

https://docs.modx.com/current/en/building-sites/sending-mail

If you have already set up email sending, that link also has troubleshooting help.

1 Like

Do I have to pay for the SMTP service?

Hi @leocubs89
You don’t need to if you use your own SMTP service (your web host may provide one).
Or you could use a commercial one that provides a free tier - usually under a certain amount of usage. e.g. MailGun, SendGrid, Postmark, SES etc.

1 Like

Thanks for this information, this has been invaluable. However, I can’t seem to get my form to send properly. Here’s what I have so far:

[[!FormIt?
   &hooks=`email,redirect`
   &emailTpl=`emailContactFormTpl`
   &emailTo=`my@email.com`
   &emailSubject=`Website Inquiry`
   &redirectTo=`1`
   &validate=`nospam:blank,
      name:required,
      email:email:required,
      subject:required,
      text:required:stripTags`
]]

[[!+fi.validation_error_message:notempty=`<p>[[!+fi.validation_error_message]]</p>`]]

<form id="contactForm" col-lg-12 col-sm-12="[[~[[*id]]]]" method="post" class="form">
    <input type="hidden" name="nospam" value="" />
    
    <div class="row">
        
        <div class="col-lg-6 col-sm-6">
            <div class="form-group">
                <label for="name">
                    Name
                    <span class="error">[[!+fi.error.name]]</span>
                </label>
                <input class="form-control" type="text" name="name" id="name" value="[[!+fi.name]]" />
            </div>
        </div>
        
        <div class="col-lg-6 col-sm-6">
            <div class="form-group">
                <label for="email">
                    Email
                    <span class="error">[[!+fi.error.email]]</span>
                </label>
                <input class="form-control" type="text" name="email" id="email" value="[[!+fi.email]]" />
            </div>
        </div>
        
        <div class="col-lg-6 col-sm-6">
            <div class="form-group">
                <label for="subject">
                    Phone Number
                </label>
                <input class="form-control" type="text" name="phone" id="phone" value="[[!+fi.phone]]" />
            </div>
        </div>
    
        <div class="col-lg-6 col-sm-6">
            <div class="form-group">
                <label for="subject">
                    Subject
                    <span class="error">[[!+fi.error.subject]]</span>
                </label>
                <input class="form-control" type="text" name="subject" id="subject" value="[[!+fi.subject]]" />
            </div>
        </div>
        
        <div class="col-lg-12 col-sm-12">
            <div class="form-group">
                <label for="text">
                    Message:
                    <span class="error">[[!+fi.error.text]]</span>
                </label>
                <textarea class="form-control" name="text" id="text" cols="55" rows="7" value="[[!+fi.text]]">[[!+fi.text]]</textarea>
            </div>
        </div>
    
        <div class="col-lg-12 col-sm-12">
            <div class="form-group checkbox">
                <label>
                    <input type="hidden" name="agree[]" value="" />
                </label>
                <ul>
                  <li>
                    <label>
                        <input type="checkbox" name="agree[]" value="yes" [[!+fi.agree:FormItIsChecked=`yes`]] /> Accept <a href="terms-conditions.html">Terms &amp; Conditions</a> And <a href="privacy-policy.html">Privacy Policy.</a>[[!+fi.error.agree]]
                    </label>
                  </li>
                </ul>
            </div>
        </div>
        
        <div class="col-lg-12 col-sm-12">
            <div class="form-group">
                <br class="clear" />
                [[-!+formit.recaptcha_html]]
                [[-!+fi.error.recaptcha]]
            
                <br class="clear" />
            
                <div class="form-buttons">
                    <input class="default-btn" type="submit" value="Submit" />
                </div>
            </div>
        </div>
    </div>
</form>

I’ve copied the code from the basic contact form in the KB, but as soon as I customize it to fit the design of the site, it seems to break. Does anything stand out that could be wrong?

Thanks!

What exactly do you mean by that?
The form works, then you add the Bootstrap classes (default-btn, col-lg-12, col-sm-12 etc.) and the form stops working?
Does the page still reload when you click the “Submit” button?

Correct. As soon as I add the Bootstrap structure, it stops working. Also no, it doesn’t redirect.

This line looks wrong. Should probably be like this:

<form id="contactForm" action="[[~[[*id]]]]" method="post" class="col-lg-12 col-sm-12 form">

Thanks! I don’t know how that got in there. But it was a combination of that and a couple of form validator scripts that were running with the template. Removed them and it worked perfectly!

Now I’m no longer afraid of forms!!

Thanks!