Handling PloneFormGen Submissions : The Email Adapter

PloneFormGen is a Plone add-on that makes it fast and easy to create forms on your website. With just a few clicks, you can quickly create contact forms, order forms, surveys or any other form for collecting and validating data submitted by site visitors.

What happens after the user submits the form? By default, PloneFormGen displays a generic "Thank You" page which simply lists the data that was entered. It also emails the data provided to the default site email address which is set in Site Setup -> Mail -> Site 'From' address.

With a few clicks, you could customize the form submission to:

• Display a custom "Thank You" page
• Configure the mailer adapter to send to different addresses based on data entered in the form
• Customize the content of emails sent (confirmation to user and/or submission to site personnel)

Customizing the "Thank You" Page

By default, PloneFormGen displays the data the user entered and a simple message when the form is submitted:

To create a more professional "Thank You" page:

1. Go to the "contents" tab of your form and select "Thank You".

2. Click the "edit" tab on the "Thank You" page.

Using the "Default" tab, you can:

• Change the Title of your page (maybe you want the title to say "Order Received")
• Change or remove the default description ("Thanks for your input.")
• Use the rich text editors to insert text, images, etc. above and below the display of the data fields submitted (these fields are empty by default)

Choose what to display:

Using the "Fields" tab, you can select whether or not to display the data that was submitted back to the user. If you wish to display the data, the default is to show all fields (whether or not data was entered for each). This may result in some unprofessional items being listed, such as Captcha text if Captcha is used on your form or field names for data the user did not submit.

On the "Fields" tab, you can specify which data elements to select. To display no data at all, simply uncheck "Show all Fields."

To display only certain fields, use the "Show Responses" widget and assign the fields you'd like to display in the right column:

To suppress empty fields from being displayed, uncheck "Include Empties."

Bypassing the "Thank You" Page

If you would prefer to have the user redirected to a page other than the "Thank You" page:

1. On the view of your form, click the "Edit" tab

2. Choose the "Overrides" section

3. In the "Custom Success Action" field, enter the URL you would like to redirect to, preceded by the text "redirect_to:string:"

Configuring the Mailer Adapter: Recipients

By default, PloneFormGen includes a mailer adapter with the form that emails any content submitted to the default site email address found within Site Setup -> Mail - Site 'From' address.

When you are adding a new form, there is a checkbox which adds the Mailer adapter to the form. If you do not want the form to send out any email, simply uncheck this box on form creation.

To stop the form from sending mail:

If you are editing an existing form and decide you do not want it to send email anymore, simply edit the form and uncheck "Mailer" under the "Action Adapters" listed. At this point, your form would do nothing but display a "Thank You" page on submission.

Say you do want your form to send emails, but you'd like to customize who receives them and what is sent. You can change the default Mailer behavior by following these steps:

1. To configure the mailer adapter, click on the "Contents" tab of your Form Folder and select "Mailer":

2. Click the "edit" tab on the Mailer adapter.

On the "Default" tab, you can change the Recipient's name and address to something other than the site default:

To customize recipients:

The "Addressing" tab allows you to customize other recipients of the email sent after submission. By default, no email is sent to anyone other than the site owner.

To send a confirmation email to the user's address that was entered in the form, choose the field name used to capture their address. In this example, the field name was titled "Your E-Mail Address" on the form displayed to the user. You may also enter additional email addresses for CC and BCC Recipients:

What if you'd like the user to determine who receives the email? For example, suppose you have a "Contact Us" form. It could have a field with multiple choices for the contact reason. The format for each item is "Display Text|email address".

This will result in a drop-down on your form for the user to select from:

When the form is submitted, the mailer will send it to the address selected by the user.

Configuring the Mailer Adapter: The Email Message

The default email message sent simply lists the data submitted:

To customize the contents of the email, select the "Message" tab. From here, you can modify the

• Subject
• Body prologue and epilogue (surrounding the data entered)
• Email Signature
• Which data fields to include and whether or not to list empty fields

The "Template" tab allows you to edit the HTML that renders the message being sent and allows you to create dynamic text.

For example, if you wanted to open the email with a salutation which included the person's name from the data entered, you could add the following to fill in the fields dynamically (assuming the shortnames of the fields on the form were first-name and last-name):

Dear <tal:block tal:content="python:request.form.get('first-name') python:request.form.get('last-name')"/>,

You can customize so much more with PloneFormGen

This is only the tip of the iceberg when it comes to the many ways you can easily customize forms on your site. In future articles, we'll cover:

• How to create custom data validation
• Styling your form with CSS
• Saving the data to a file or database
• Sending data to Salesforce
• How to group form fields together and create multi-page forms
• Creating content items within the site from the data submitted
• And more!

Was this article useful? Let us know in the comments and be sure to sign up for our Plone & Python How-To digests to receive more how-to guides as soon as they are published!