A frequently-asked question is, "how do I modify the email in an email submit button?" Usually, the reason behind the question is that a form should either be routed to a specific person depending on data entered at runtime (so you can’t predict the data and therefore you can’t set the email submit button accordingly at design-time) or perhaps the form even presents a list of possible recipients and the user must choose which person to send the submission data to.
The Secret
The secret to changing the email recipient for an email submit button (or even changing it for a regular button which you’ve turned into a submit button using the "Object palette > Field tab > Control Type > Submit property") is to set the "target" attribute of the <submit> node that is part of the button’s Click event. The "target" specifies the URL to which the data will be submitted. HTTP and mailto are valid protocols.
In XFA, the difference between a regular button with Click event script and a submit button which submits form data when it’s clicked is that the submit button’s Click event has a <submit> node instead of a <script> node.
A regular button’s Click event:
<event activity="click">
<script contentType="application/x-javascript">
// your JavaScript code here...
</script>
</event>
versus a submit button’s Click event (set to email form data in this case because of the "mailto" protocol):
<event activity="click">
<submit format="xml" textEncoding="UTF-8" target="mailto:"/>
</event>
How is it done?
Changing the recipient is done simply by setting the submit button’s target appropriately, following the rules of the protocol you wish to use. In this case, we’ll be using the mailto protocol. Of course, we can do much more than change the recipient: We can actually specify multiple recipients, CC some others, BCC others still, specify any subject we want and even specify a customized email body (message)! All that needs to be done is to apply the mailto protocol when specifying the submit button’s target.
For example, setting the target to the following string would create an email with two recipients (one "to" and one CC’d), a subject and a body:
mailto:john@asdf.com?cc=lisa@adsf.com&subject=Re: New Account Opening&body=Thank%20you%21"
Note that the body must be URL-encoded using the "%" codes for non-URL characters such as "%20" for a space and "%21" for an exclamation mark (!). Thankfully, we can use the encodeURIComponent(string) method in JavaScript to do that part for us!
The most difficult part of all this is finding the Click event (since there could be multiple <event> nodes specified on a single field, one for each event that does something) and locating the <submit> node inside.
Sample Form
To illustrate how this is done, I’ve created a sample form that submits an address block as data and provides fields for specifying the recipient(s), CC list, BCC list, subject and body of the email.
The result of the above settings is a new email with the specified recipients, subject and body, along with the attached XML data file:
In order to accomplish this, I used the two-button submit technique where a regular button is used to set the properties on a hidden email submit button. Doing it this way also lets me easily prevent the submission if there are no recipients ("to") selected. (Note that the To, CC and BCC fields are multi-select list boxes so you can choose multiple email addresses.) You’ll be interested in the script in the "Send" button’s Click event.
Download Sample [pdf]
Minimum Requirements: Designer 8.0, Acrobat/Reader 8.0 for this form since it uses functions that are part of the new List Object API which was introduced with the 8.0 versions however you could access the selected items differently and get this to work in previous versions as well.
Posted by Stefan Cameron on August 28th, 2008
Filed under
Events,
Scripting,
Tutorials,
XFA
