Search: Go

Advanced Search

• Contact Us

Form Mailer

A Form Mailer is a content type that allows you to set up a form on the website, and have the data a user enters in that form sent to an email address you specify.

A Form Mailer is a tool for setting up a form on the website. At the time of writing, it's the only tool we have to do this, short of coding the form directly in HTML. Form Mailers are very flexible, but their primary function is quite simple - take data the user enters in a form and send it to an email address. So far, we've generally used Form Mailers for order forms, such as the Fast Materials form; but to give you a sense of the how flexible the tool is, the Send to a Friend form is also just a Form Mailer that's been customized to send the URL of the current page to the addresses the user enters.

Creating a Form Mailer

In order to create a Form Mailer, this content type must be enabled in the folder you're adding to [XXX: link]. As with all other content, you can use the Add New Item button to add a new Form Mailer [XXX: link].

At this point it might be good to note that, especially if you're making an order form or some other form with the user info fields (address and so on), it will make your life much easier to copy an existing Form Mailer and modify it, rather than starting from scratch. Setting up a form can be a painstaking process, and you're better off giving yourself a head start.

The Edit Form Mailer page is a little different than most edit screens. Forms are complicated, and there are a lot of options, so the settings for the Form Mailer are broken up into different pages - you can see the titles of these pages in the links at the top of the Edit screen:

[default]   [Mail Message]   [Mail Header]   [Template]   [Form]   [Encryption]  [Controller]   [Sent Response]

Each of these pages works like a normal Edit screen, and you can move between them by clicking the links at the top or clicking the Next button at the bottom of the screen.

Important Note: You must click either the Save or Next button at the bottom of any of these screens to save your changes. If you make changes in some fields, and then click one of the links above, your changes will not be saved.

The eight pages of the Edit screen will allow you to set up the page the form is on, change some settings on the form, set up a page for the user to see after they've submitted the form, and define settings for the email that gets sent. However, they don't allow you to set up the form itself. To define the fields and headings for the actual form, there's an entirely different interface, which you can access via the Modify Form (ZMI) tab.  We'll deal with the Edit tab first, and then the Modify Form tab.

General Settings: The Edit Tab

As noted above, all of the general settings for the form can be set in the eight screens of the Edit tab. Don't get freaked out by how many screens there are - they're all short, and several of them can be completely ignored. We'll go through them one by one.

[default]
The Default screen has the same basic elements that you'll find on almost all content types: Short Name, Title, and Description. These work exactly as you'd expect: Short Name defines the id in the URL; Title works like all titles in the system, showing up as the page title and in the navigation; Description shows up below the title, set off from page content by a dotted line.

[Mail Message]
The Mail Message screen defines basic settings about how the email that the form sends will be set up. The Subject is the subject of the email, and the three Body fields contain text that gets added to the email before or after the actual data from the form.

The Subject field, like several fields in the Edit tab, is a TALES field - if you know the special syntax of TALES expressions, you can use this to put variables and dynamic elements into the field. If you don't know TALES, just follow the help text on the page and put in "string:This is some text for the subject". If you forget the "string:" prefix, it'll give you an error when you try to save.

[Mail Header]
Generally, the only things you need to worry about on the Mail Header screen are the Recipient's Name and the Recipient's Email Address. Again, these are only defining settings for the email that the form will send. Usually, the Recipient's Email Address will be something like "string:fast@oxfamamerica.org", or some other email address that you want to get the data.

All of the fields on this screen are TALES fields - see the note above. Ignore Additional Headers completely, as you'll never need to mess with it.

[Template]
The Template screen is, admittedly, totally scary. The Template defines how the data gets formatted in the email, and it's very flexible, and thus very complicated. Fortunately, you have simple choice of options (unless you know TALES, in which case you can do a lot more):

1. Leave the default template. This will result in an ugly but serviceable email.
2. Cut and paste a different template. At the moment, the only other template we've created is this one, which formats the email for an order form.

[Form]
The Form screen allows you to set up rich-text content on the page. The first field, Text (Prepended), works like a normal Body Text field - you can add rich content here, including links and whatnot, and it will show up at the top of the page, between the Description and the form itself. The second field, Text (Appended), is a plain-text field (well, you might be able to do straight HTML if you really wanted) that will show up at the bottom of the page, after the form itself.

The Buttons field is a little odd - it's a quick, shorthand way of setting what the submit button for the form looks like. Generally what I do here is the following:

1. Delete the second line, which reads "Reset|reset|reset|standalone". No one likes a reset button - it clears the form, and if you fill out a lot of info and then it reset by mistake, you end up really annoyed.
2. Change the very first part of the first line to whatever text you want on the submit button. For example, if you want it to say, "Submit this form, already", you'd change the line to read "Submit this form, already|submit|submit|context".

You can do other stuff with the buttons as well, but unless you really know what you're doing, I don't recommend it.

[Encryption] and [Controller]
Just ignore these two screens. Trust me.

[Sent Response]
The Sent Response screen is what the user will see when they successfully submit the form. The Message field works just like a Body Text field. If this is an order form, I might put information about how long it will take the order to be processed, and contact information if the user has any questions about their order.

Form Settings: The Modify Form Tab

Now that you've set up all the settings for the page and the email, you probably want to do something more with the form than just getting the Full Name, Email, and Message that make up the default form. You can change the setup of the form in the Modify Form (ZMI) tab. I strongly recommend right-clicking and opening this tab in a new window, as there's no easy way to get back to Plone once you're in there.

I say "back to Plone" because this interface actually lives outside Plone, in Zope. "ZMI" stands for Zope Management Interface, which is an interface used to manage some of the core technology of the site. Unless you're a site manager, this may be the only time you ever need to see this interface. There are a lot of unfamiliar and possibly confusing things in this interface, but you only need to worry about the ones I discuss here.

Setup of the ZMI
The ZMI is different from Plone, but not that different. You've still got tabs across the top, and the Contents tab, where you start out, shows you a list of items not that different from the Plone Contents tab. Each item in the contents is a field in the form; if you're starting this form from scratch, there should be three fields, email, fullname, and message. One difference between the ZMI and Plone is that the Contents view shows items as Id (Title), rather than the simpler Title list that Plone displays (as you may know, "Id" is just a synonym for the Plone "Short Name"). At the bottom of the contents list are a number of buttons - the only ones you'll probably need to use are Rename and Delete. These work the same way as in Plone - check the box next to the item(s) you want to affect, and hit the button.

Above the list of contents, to the right, is a pulldown menu similar to the Add New Item menu in Plone. All of the items in this pulldown menu are different kinds of fields - I'll go through them in a sec.

Above the pulldown menu is a link entitled "Help!". This link will also appear on the Edit tab for each field. Clicking it will give you a pretty good explanation of the page you're on, though I should warn that it may not be as user-friendly as these docs.

At the top of the page, as noted, are a bunch of tabs, with Contents selected. Ease your worried mind: the only tabs you will need to worry about are Contents and Order. Ignore everything else.

About Form Fields
If you've ever used a form on the web, and you have, you know there are different types of fields: text fields where you can type, checkboxes you can check or uncheck, pulldown menus, etc. Each of these allows the user to enter a different kind of data: text, true/false, one choice among specific options, etc. Form Mailers allow you to use all of these fields, though some you'll never use. In a Form Mailer, each field also has a specific kind of "validation" - that is, a way that the system checks to see if the data the user entered is okay. If you create an EmailField, for example, when the user submits the form, the system will check to see whether the text the user put in this field is a valid email address. This kind of validation is useful to the user, who gets warned about their mistakes, and to the recipient of the data, who has fewer messages from "asdfasd" to bother them. A number of the fields available in Form Mailer look the same, and are different only in the type of data they require.

Here are all the available fields in the pulldown menu:

• CheckBoxField: A checkbox that will give a value of True or False.
  
• DateTimeField: A field with pulldown menus for day, month, year and hour, minute, second - I believe you can have just the date or just the time if you want.
  
• EmailField: A text field that requires the user to enter a valid email address.
  
• FileField: Allows the user to upload a file. Does not work with Form Mailer.
  
• FloatField: Ignore.
  
• IntegerField: A text field that requires the user to enter a number. Use OrderFormField instead for order forms.
  
• LabelField: This isn't really a field at all - it allows you to stick a "label," i.e. a line of bold text, somewhere in the middle of the form. Usually you'd be better off using Groups - see below.
  
• LinesField: Ignore.
  
• LinkField: This is a text field that takes a URL, and theoretically can be set to verify whether the URL works before submitting the form. I haven't tested this and don't really recommend it.
  
• ListField: This is a pulldown menu where the user can pick one of a list of items you specify.
  
• MultiCheckBoxField: This is a set of checkboxes, allowing the user to pick one or more items out of a list you specify (e.g. "I am interested in: [ ] Hunger [ ] Poverty [ ] Social injustice").
  
• MultiListField: This is a multi-select field - like a pulldown menu, but with multiple options visible. The user can select more than one option by Ctrl-clicking.
  
• OrderFormField: This is a field type I created specifically for order forms: it requires a number, it displays to the left of the title, and it has an optional link for more information.
  
• PasswordField: A password field will mask any text the user types with "****". Other than that, it's just a text field - you'll probably never use this.
  
• PatternField: Ignore.
  
• RadioField: Radio buttons are the little circular buttons that allow the user to pick one out of a set of choices. The functionality is exactly the same as a pulldown menu, but you can see all the options on the page.
  
• RawTextAreaField: Ignore.
  
• StringField: This is a basic text field (in programming speak, any amount of text is called a "string").
  
• TextAreaField: A text area is a larger text field with multiple lines, suitable for comments or longer messages.

Adding and Editing Fields
To add a field, just select it from the pulldown menu (you probably won't even need to hit Add). You'll be prompted for an Id (same as Short Name) and a Title. The Id doesn't really matter at all in this context, but you should probably have something legible, like "address1" or "fast_poster". The title will be shown with the field on the form. After you fill in the Title, you can hit Add or Add and Edit - you usually will want the Add and Edit button, which takes you to the Edit screen for that field. Add will take you back to the form, giving your field all the standard defaults, which are not always the best.

If you click Add and Edit, or if you click on a field from the form Contents view, you'll go to the edit screen for that field. The edit screen looks a little different for each type of field, and I'm not going to go through each here - the best option is to hit the "Help!" link on a screen to get an explanation of all the elements.

Some general documentation on the edit screen:

A field has a number of properties that determine its look and feel as well as its behavior; which properties appear in this view depends on what kind of field you are editing. Each field has two sets of properties; widget properties and validator properties.

Widget Properties

The widget properties determine the look and feel of the field that you see on the web page. One common widget property shared by all fields is the Title, explained above. Another very common widget property is the "Default" value of the widget. This is what will be filled in by default, before the user changes anything in the form. Many widgets also have size information; the StringField for instance has a "Display width" property which determines how large the field should appear on the screen, as well as a "Maximum input" property that determines how much the user can enter. For some widget properties, such as "Maximum input" in StringField, you can set the value to "0"; in that case the system won't care how much the user inputs.

Validator Properties

This set of properties determines how the system validates the information that is submitted for this field (see the explanation of validation, above). The most common validator property, and the only one you'll generally have to worry about, is the "required" property. If a field is required, the user cannot leave the field empty when submitting the form, or they'll get an error. It's a slightly annoying aspect of fields in Form Mailer that they all default to Required, which is often not what you want.

That's basically all I'll say about editing fields. There are a lot of settings, and I encourage you to play around a little bit and test different options. As noted above, it can take a long time to make a form field by field, so I suggest copying an existing Form Mailer and working from there. If you get lost while editing a field, click the "form" link in the left frame to get back to the form menu.

Reordering and Grouping Form Fields
You can make fields until the cows come home, but at the end you're not going to be happy unless you can arrange them in the order you want, possibly grouping some fields together under a common header. That's where the Order tab of the form comes in.

The Order tab allows you to change the order in which fields should be displayed in the form. You can also group fields together. Note that you cannot add or remove any fields in this form; you have to use the main Contents tab of the form for that.

Any field that gets added to the form ends up in the first group, called "Default". This group always exists and cannot be removed. Fields in the Default group will be shown at the beginning of the form, without a header. Each other group will be set off by a dashed line and will include the name of the group as a header above the fields.

Reordering fields inside a group

You can reorder fields in a group by moving them up and down in the group. Select the field you want to move using the checkbox in front of the field id. Then click on the Move Up or Move Dn button, to move the field up or down respectively. You will see a feedback message at the top of the screen. You can only move a single field at a time.

Creating a new group

The first group has a button called Create at the bottom, with an input box above it. Fill in the name of the new group that you want to create there, and press the Create button. The new group will be added (as the last group visible).

Moving fields to a different group

When you create a new group, it remains empty. You can move several fields into a group by using the Transfer button of a group. First select one or more fields in an old group that you want to move away. Then, use the Move to: dropdown list to select the group to which you want to move the selected fields. Then, press the Transfer button. The fields should now disappear from the origin group and appear in the target group.

Reordering groups

You can change the order of the groups by using the Move Up and Move Dn buttons in the Group section of a group. This moves the entire group in the group order. You cannot move the first group (and it therefore has no group movement buttons).

Renaming groups

You can rename a group by filling in the new name in the input box above the Rename button, and then pressing that button.

Removing groups

You can remove a group by pressing the Remove button in the Group section of the group. The entire group will disappear. Any fields that were in the group will move to the bottom of the first group; you cannot lose any fields this way.

And that's basically it. There's a lot more that's possible with Form Mailers, but this should be enough to get you started.