Personal tools
You are here: Home Documentation Tutorials Customizing PloneFormGen
Navigation
 
Document Actions

Customizing PloneFormGen

Note: Return to tutorial view.

Here are a number of ways you can customize PloneFormGen.

Send an Email to the Form Submitter

The Mailer Adapter normally will send email only to a predefined set of email addresses. However, if you want the person submitting the form to receive an email, you must dynamically override the default behavior of the Mailer Adapter.

Provided that you have a field for capturing an email address in your form, you can use the address that someone enters to mail that person a customizable message. By default, when you create a new Form Folder, PloneFormGen generates an email field for you with the short name replyto. If you have deleted this field, or want to rename the field, be sure to take note of what the short name is for your email address field. You will need this information to complete the override.

Setting the Override

Go to your Form Folder, and Edit the Mailer Adapter. Then click on the Overrides tab. You should see a screen that looks like this:

mailer-adapter-overrides.gif

 

Notice the Recipient Expression field. Paste the following string into that field:

request/form/replyto

Where "replyto" is the short name of your email address field. You have just entered a TALES expresssion that will automatically retrieve the address someone enters in your email address field after submitting the form and use that address to direct the Mailer template to.

Note that you can use multiple Mailer Adapters in a single form. This way you can have one adapter for sending the form submitter a message AND have another for sending a message to yourself.

Customize the Email Message and Template

Now that you have configured the recipient expression override you may wish to customize the body and/or template of the email that will be sent to the form submitter. This can be done via the Message and Template tabs of the Mailer Adapter.

The Message tab allows you to enter plain-text content before and after the email template. By default, the email template simply sends a listing of form data in a Fieldname-Value format. The HTML used to render this listing is called a Definition List, which uses the HTML tags <dl>, <dt>, and <dd>.

Additionally, the template uses Plone templating language TALES. If you are not familiar with HTML or TALES you should leave the template alone and just make use of the Message tab for including your content. For some pointers on how to customize the mailer template, read the last section of this tutorial.

 

 

Customize the From Address

With a simply override, you can customize the from address that each form folder will use to send email.

By default, PloneFormGen will use your site-wide email address as the from address for sending email. This address can be changed through the ZMI or Plone Control Panel depending on your version of Plone. However, this is a single global address so you cannot specify a from address for a single form in this way. Instead you must use a simple override in the Mailer Adapter of your form.

mailer-adapter-overrides.gif

Edit your Mailer Adapter and click on the Overrides tab. You should see a screen like the one to the left. Notice the Sender Expression field. Paste this line of code into that field, where 'your address' is simply the email address you wish to use for the From address.

string:your address

Be sure to Save before navigating away from this page.

Note that you can set a custom From address for each mailer in your Form Folder. 

 

 

 

 

 

 

 

 

 

 

Setting a Custom Redirect

PloneFormGen normally displays the Thank You Page after someone submits a form. If you'd rather point them to a URL, you can do so by setting a custom redirect in the Form Folder.

For some forms you build, you may wish to direct your site visitor to a specified URL instead of the Thank You Page after they submit the form. In order to do this, you must employ an override on the Form Folder.

Edit the Form Folder then click on the Overrides tab. Notice the first field at the top, labeled Custom Success Action.

form-folder-overrides.gif
If you read through the help text for the field you will notice that this field requires CMFFormController actions. However the help text does provide an example for setting a custom redirect.

Paste the following code into the field:

redirect_to:string:thanks-page

Where 'thanks-page' is the Short Name of the object you wish to point to after the form has been submitted. Keep in mind that simply indicating the short name may not be enough information - the string is looking for a relative URL, that is, a web address defined in relation to where the Form Folder is in your site's file structure. You can either use the "../../" method or use an absolute URL (i.e. http://www.mysite.org/forms/thanks-page).

 

Customize the Subject Line with Dynamic Values

By adding an override in the Mailer Adapter you can dynamically generate a subject line for your email.

You can define an email subject line in PloneFormGen's Mailer Adapter under the Message tab in one of two ways. You can either set a static subject in the Subject field, or you can extract a subject from any available string field in your form using the Extract Subject From drop-down menu.

However, you can also create a mail merge-like subject line that combines a piece of static text with a piece of dynamic text by using the Overrides tab of the Mailer Adapter. In the Overrides tab, notice the Subject Expression field. Paste the following line of code in this field:

python:'Thank you ' + request.get('my-field-id', 'default-value')

Where 'Thank you' is a string of text of your choosing, 'my-field-id' is the Short Name of the field from which you want to extract dynamic content, and 'default-value' is a string of text of your choosing used if no input is given for the 'my-field-id' field.

Let's consider an example. Let's say you used a First Name field for the dynamic component, and you used 'Friend' for the default-value. The subject line would then become:

  • Thank you George (with an input of George)
  • Thank you Friend (with no input)

 

 

Customizing the Mailer Template

How to customize the mailer adapter template to include your own message and how to include mail merge-like dynamic content.

mailer-adapter-template.gif

If you wish to customize the mailer adapter, you must have some familiarity with HTML, and TALES preferably. To get started, edit the Mailer Adapter and click on the Template tab to see the email template.

You should see a chunk on HTML and TALES similar to the screen shot to the left. The default template is designed to grab all three plain-text fields found in the Message tab, and display all the form data that the site visitor submitted. If you do not put any text into the Message fields (prepend, append, and signature), no text will render so it is not necessary generally to remove those lines of code.

However, if you do not want the form data to be part of your email message, you can remove the definition list that renders this information. The code in question is the following:

    <dl>
        <tal:block repeat="field options/wrappedFields">
            <dt tal:content="field/fgField/widget/label" />
            <dd tal:content="structure python:field.htmlValue(request)" />
        </tal:block>
    </dl>

Simply highlight and remove this block of HTML and you're all set. Now you can enter your own HTML and TALES code to create a customized email message. Use only non-deprecated HTML tags to format your message.

If you wish to include dynamic content in the template you must be familiar with TALES. Below is an example of a TALES expression that grabs the first-name field data and puts it into the email template.

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

'first-name' is the shortname of the First Name string field. 'Supporter' is the default value that will be used if no First Name data is submitted. For required fields, it's probably not necessary to define a default value.

 

 

Still Stumped?
If you've still got questions about Plone, here are your best bets for finding out more:
 

This site conforms to the following standards: