Forms and information collection #

This page is for developers who need forms on a site: contact, feedback, polls, event sign-up, lead capture. Exponential builds most of them from the content model: a form is an object of a class whose attributes are marked information collector, editors create and change forms like any content, and the answers are stored and mailed by the kernel.

Contents #

1. How it works
2. A form class
3. The form template
4. After sending: result page and mail
5. Settings per form type
6. Reading and exporting answers
7. Spam and privacy
8. When to write a module instead

How it works #

form object (class with collector attributes), full view
  -> <form> posts to /content/action with ActionCollectInformation
     -> the kernel validates each collector attribute, stores one collection
        -> result page (content/collectedinfo/<type>.tpl) and, if enabled, a mail (content/collectedinfomail/<type>.tpl)

Answers are not content objects: they are collections in their own tables, read under Setup > Collected information (Collected information).

A form class #

Create a class (for example exp_contact_form) with:

• normal attributes for what editors write: a title, an intro (ezxmltext), and, if you use them, the attributes that collect.ini reads per object (see below);
• information collector attributes for what visitors fill: Text line for a name, Email for the address, Text block for the message, Selection for a choice, Checkbox for consent.

Mark the collector attributes Required where the form needs them; the kernel then refuses incomplete answers with a validation message.

The form template #

The form object's full view prints the form. Each collector attribute is drawn with attribute_view_gui, which uses the datatype's collect template and prints an input; the submit button is named ActionCollectInformation, with the hidden fields ContentNodeID, ContentObjectID and ViewMode. A complete template with labels and validation messages: Forms in templates. Start from the form template of the design you build on, so the hidden fields and the form token stay right, and give inputs ids for their labels (Accessible forms).

After sending: result page and mail #

The result page is content/collectedinfo/<type>.tpl and the mail content/collectedinfomail/<type>.tpl, where the type comes from collect.ini (shipped: form, poll, feedback). Override both in your design: the result page for the thank-you message, the mail for its subject and body (set with {set-block scope=root variable=subject}). Test mail with a recipient at example.invalid and a file transport on development machines.

Settings per form type #

settings/collect.ini decides behavior per type, and lets a form object override it through an attribute of its own:

So one class can serve many forms, and an editor can, for example, choose per form where the answers go. Put your changes in your extension's collect.ini.append.php.

Reading and exporting answers #

Setup > Collected information lists the objects that collected, with each object's collections, a CSV export and removal after confirmation; it needs the policy infocollector/read. In templates, the content fetch functions collected_info_count, collected_info_count_list, collected_info_collection and collected_info_list read answers, for example to show poll results. The bccie extension of the default distribution exports collected information as well (Mapping content: forms).

Spam and privacy #

• Add a captcha datatype (recaptcha or hcaptcha) as a collector attribute to public forms (Choosing datatypes).
• Keep the form token (ezformtoken) in the template; do not remove hidden fields the original prints.
• Collect only what the form needs, say on the form what happens with the answers, and remove old collections on a schedule; answers are personal data (Privacy standards).
• Never print answers back unwashed.

When to write a module instead #

Information collection fits forms whose answers are stored and mailed. When a form must create content (a member submits an article), call another system, or follow a multi-step flow, write a module view with a policy in your extension, or let users create content with content/create limited by role (Modules and views, Forms and actions).

Related pages #

• Collected information
• Workflows and triggers
• Users and registration
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.