Answered formit question

Often to avoid huge, long scrolling forms, designers like to break them up into several pages. Here's a simple, step by step example of how to implement that in MODX with the FormIt add-on package.

1. I got the "quick and dirty" of how to do this from this forum post (thanks odeclas) http://modxcms.com/forums/index.php/topic,60268.msg342846.html#msg342846

2. I'm assuming you've used FormIt before, but haven't used it for a multipage form. Official FormIt documentation can be found here: http://rtfm.modx.com/display/ADDON/FormIt

3. This solution uses FormIt, which comes with FormItRetriever. You'll need both, because the way this works is that on submitting the first page, FormIt simply "stores" the results - then FormItRetriever "retrieves" them and puts them into placeholders in hidden input fields on the next page. Upon submitting the second page, all of it gets output (to email, in this example).

4. First page FormIt snippet call:

[[!FormIt? &hooks=`redirect` &store=`1` &redirectTo=`ID` &validate=`this_field:required, that_field:required, other_required_fields:required`]]

Break it down:
!FormIt? » Calls the snippet.
&hooks » Notice we don't have email, math, or anything else here. I'm just redirecting to the next page. Someone might suggest I have a spam hook or something here - I don't think it's necessary yet.
&store » Tells FormIt to store the results.
&redirectTo » Replace ID with document ID of the next form page.
&validate » This is standard FormIt validation - add any required fields from your form. This page of the form will not submit until it is validated.

There's nothing special about the form html on this first page, so onwards...

5. Second page FormIt snippet call:

[[!FormIt? &hooks=`spam,email,redirect` &emailTpl=`emailTplChunk` &emailSubject=`Multipage Form by [[+name]]` &emailTo=`[email protected]` &validate=`name:required:minLength=`2`, email:email:required, 2nd_page_required_fields:required` &redirectTo=`ID2`]]

Break it down:
!FormIt? » You must call the snippet again from this page, if that wasn't obvious.
&hooks » Here you can use any FormIt hooks you'd normally use. In this example, FormIt checks for spam, emails the form results and redirects to a Thank You page.
&emailTpl » Name of your email template chunk. Required - otherwise FormIt sends a list of fields & values.
&emailSubject » Subject of the email report - notice you can use a placeholder for any of the form's fields.
&emailTo » Recipient array, comma separated.
&redirectTo » Replace ID2 with document ID of your Thank You page.
&validate » More validation options. For usage and a list of built-in validators, check the documentation here: http://rtfm.modx.com/display/ADDON/FormIt.Validators

6. Here's the important part!!

[[!FormItRetriever]]

You must also call FormItRetriever on this page. I've done it immediately following the FormIt snippet call and preceding the actual html form. Not sure if it's necessary to do it in that order, but that seems to work But wait....now that we've retrieved the previous page's form data, where does it go?

7. Add placeholders to output the form data:

  <input type="hidden" name="this_field" value="[[+fi.this_field]]"> 
  <input type="hidden" name="that_field" value="[[+fi.that_field]]">

These hidden fields are where FormItRetriever will output the stored form data from the first page. Notice the prefix "fi." They should be nested inside your <form> element and I have them grouped preceding the second page form fields, but I suppose they could be anywhere in the form.
In this example, ONLY "this_field" and "that_field" will be output!! All other fields from the first page will be discarded if I don't add placeholders for them! Tricky, hey?

8. Your email template
Remember to include placeholders from BOTH pages of your form in the email template chunk. No placeholder = nowhere to output data = missing data!

So that's it. Hope this helps. Thanks MODX Team for a great platform, and FormIt developers for an awesome add-on...

Please add your comments to make this tutorial better (or at least suggest ways that I can make it better, or point out mistakes)