**Originally posted in the MODX Community Forums
Often to avoid huge, long scrolling forms, designers like to break them up into several pages. Here's a simple, step by step tutorial on how to implement that in MODX with the FormIt add-on package.
I got the "quick and dirty" of how to do this from this forum post (thanks odeclas)
I'm assuming you've used FormIt before, but haven't used it for a multipage form. Official FormIt documentation can be found here: https://docs.modx.com/extras/revo/formit
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).
First page FormIt snippet call:
[[!FormIt? &hooks=`redirect` &store=`1` &redirectTo=`42` &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 42 with Resource 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...
Second page FormIt snippet call:
[[!FormIt? &hooks=`spam,email,redirect` &emailTpl=`emailTplChunk` &emailSubject=`Multipage Form` &emailTo=`[email protected]` &validate=`name:required:minLength=^2^, email:email:required, 2nd_page_required_fields:required` &redirectTo=`43` ]]
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 43 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: https://docs.modx.com/extras/revo/formit/formit.validators
Here's the important part!!
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 :P But wait....now that we've retrieved the previous page's form data, where does it go?
Add placeholders to output the form data:
<input type="hidden" value="[[!+fi.this_field]]"> <input type="hidden" value="[[!+fi.that_field]]">
These hidden fields are where FormItRetriever will output the stored form data from the first page. They should be nested inside your
<form> element. The placeholders use the prefix "fi." and are called uncacheable.
In this example, only the values for "this_field" and "that_field" will be output. All other fields from the first page will be discarded if placeholders are not added for them! The FormItRetriever Snippet sets placeholders on this, second page, to be re-posted.
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)