Support the team building MODX with a monthly donation.
The budget raised through OpenCollective is transparent, including payouts, and any contributor can apply to be paid for their work on MODX.
$407 per month—let's make that $500!Learn more
FormIt email Hook¶
The email hook will email out your form contents to any email(s).
|emailTpl||Required. Tpl chunk for email message. If one is not specified, it will send a list of fields with their values.|
|emailSubject||The subject of the email.|
|emailUseFieldForSubject||If 1, and the field 'subject' is passed, then will use that field's value as the email's subject line.|
|emailTo||A comma-separated list of emails to send to.|
|emailToName||Optional. A comma-separated list of names to pair with the emailTo values.|
|emailFrom||Optional. If set, will specify the From: address for the email. If not set, will first look for an
|emailFromName||Optional. If set, will specify the From: name for the email.|
|emailHtml||Optional. Whether or not the email should be in HTML-format. Defaults to 1.|
|emailConvertNewlines||Optional. If set to 1, will convert all newlines to br tags.|
|emailReplyTo||An email to set as the reply-to. If not set, will first look for an
|emailReplyToName||Optional. The name for the Reply-To field.|
|emailCC||A comma-separated list of emails to send via cc.|
|emailCCName||Optional. A comma-separated list of names to pair with the emailCC values.|
|emailBCC||A comma-separated list of emails to send via bcc.|
|emailBCCName||Optional. A comma-separated list of names to pair with the emailBCC values.|
|emailMultiWrapper||Wraps values submitted by checkboxes/multi-selects with this value. Defaults to just the value. (1.6.0+)|
|emailMultiSeparator||Separates checkboxes/multi-selects with this value. Defaults to a newline. (1.6.0+)|
|emailSelectField||The name of the form field, that selects the email addresses to send to. (4.2.5+)|
|emailSelectTo||A semicolon separated list of comma separated email addresses to send to. (4.2.5+)|
|emailSelectToName||A semicolon separated list of comma separated email names to send to. (4.2.5+)|
Any of the email hook properties can have placeholders of field names from your form in them that will be evaluated.
Simply specify it as a hook in your FormIt call, and then specify the email-specific properties in the FormIt call as well.
[[!FormIt? ... &hooks=`email` &emailTpl=`CentralizedDebtObligationEmailTpl` &emailSubject=`Some Sucker Bought Another CDO` &emailTofirstname.lastname@example.org` &emailCCemail@example.com` &emailBCCfirstname.lastname@example.org` &emailBCCName=`CDO Fraud Informant` ]]
Note the &emailTpl property points to the name of a Chunk. In that Chunk, you'll have placeholders for each field in your form. Our Chunk could look like this:
<p>Hello,</p> <p>[[+name]] just purchased the CDO package: [[+cdo_package]].</p> <p>Their email: [[+email]]</p> <p>Thanks!</p>
This assumes, of course, that you have the fields "name", "cdo_package" and "email" in your form.
Specifying Dynamic To Addresses¶
FormIt, as of 4.2.5+, could select the receiver of the mail by the numeric value of a field i.e. by the option value of a select. By doing this, you could avoid to create a spoofable form field, where a frontend user could submit any mail address quite easily. The frontend user would only see a numbered list of receivers that are translated to email addresses by FormIt properties.
For this, you could use the following FormIt properties
&emailSelectToemail@example.com,firstname.lastname@example.org;email@example.com` &emailSelectToName=`Mail1,Mail2;Different` &emailSelectField=`emailselect`
and the following form field
<select name="emailselect"> <option value="1" [[!+fi.emailselect:default=`1`:FormItIsSelected=`1`]]>Address 1</option> <option value="2" [[!+fi.emailselect:default=`1`:FormItIsSelected=`2`]]>Address 2</option> </select>
If Address 1 is selected, the mail would be sent to
firstname.lastname@example.org,email@example.com, if Address 2 is selected, the mail would be sent to
Using a Subject Field as the Email Subject Line¶
Let's say you have a subject field in your form. You want that to be the subject of the email sent out. The email hook has the ability to do this:
[[!FormIt? ... &emailUseFieldForSubject=`1` ]]
This will then look for a field named "subject" that will be used in the email. If it's not found or empty, it will default to the &emailSubject property.
Handling Checkboxes and Multi-Selects in the Email¶
FormIt, as of 1.6.0+, will automatically handle checkboxes and combine them into one field. You can use the &emailMultiSeparator and &emailMultiWrapper properties to specify how they are joined. For example, to wrap checkboxes in LI tags:
[[!FormIt? ... &emailMultiWrapper=`<li>[[+value]]</li>` ]]
Or just to separate them with BR tags:
[[!FormIt? ... &emailMultiSeparator=`<br />` ]]