How to Create eZ Publish Forms

Defining how information is collected

The settings/collect.ini file contains some useful form options.

Recall from the first article in this series that eZ Publish reads basic settings from the default INI files, which are overriden by any settings in the specific siteaccess overrides, which are overridden by settings in the global override files. You should never modify the default INI files.

The settings below should be created in the file collect.ini.append.php located either:

• In the directory for the siteaccess (in settings/siteaccess/[name_of_siteaccess]/) that will display the form; or
• In the override directory (in settings/override/), meaning it will apply to all siteaccesses.

If the override file does not already exist, you must create it.

The sections below show the settings that need to be included in the INI file. Note that lines starting with hash symbols are comments.

[InfoSettings] block

The setting below specifies that there is an information collector based on the class ID “membership_application_form”, and that the identifier for the information collector is the same as the class name.

[InfoSettings]
# Matches class id or identifier to information collection type
TypeList[membership_application_form]=membership_application_form

[EmailSettings] block

Sometimes it is useful to send an email summarizing the results of each form submission. This is not required for objects such as polls, but we will use it in our membership application form.

[EmailSettings]
# Matches class id or identifier to information collection type
# SendEmailList[poll]=disabled
SendEmailList[membership_application_form]=enabled

[DisplaySettings] block

The DisplayList setting specifies the page that should be loaded after the form is submitted. There are three main options:

• Result – Displays a "result" template (such as a poll result or a confirmation page), typically located in
  [design_extension]/templates/content/collectedinfo/. This is the option we will choose for our membership application form.
• URL – Load a specific URL.
• Node – Redirect back to the original content node. For example, a user filling in a form would be redirected back to the page containing the blank form. In this case, you can configure the form template to display some confirmation text above the blank form to acknowledge the submission.

[DisplaySettings]
# result  - Display IC result, for instance poll result or your form data
# redirect - Redirect to a specific url
# node    - Redirect back to content node
# Matches class id or identifier to information collection type
#DisplayList[poll]=result
DisplayList[membership_application_form]=result

[CollectionSettings] block

Some forms need to be available to anonymous users. This is determined by the setting below.

[CollectionSettings]
# if enabled then information from anonymous users can be collected
# CollectAnonymousData=enabled
# Same as CollectAnonymousData but is a list of IC types and
# their override settings, if specified it will override default setting
CollectAnonymousDataList[membership_application_form]=enabled

The CollectionUserData setting specifies how to handle users submitting a form multiple times, and is explained well in the comments to the setting.

# How information collection is handled in terms of user identification
#
# multiple - each user can submit multiple data
# unique   - one set of data per user, if already exists give a warning
# overwrite - one set of data per user but new entry overwrites old one
CollectionUserData=multiple
# Matches class id or identifier to information collection type
#CollectionUserDataList[feedback]=multiple
CollectionUserDataList[membership_application_form]=multiple

Making the form visible in the site’s menus

eZ Publish does not automatically include objects of a new class in the default top or left site menus. For example, the top menu displays the objects that are directly below the top-level node of the Content branch, but only for the classes specified in menu.ini. Similarly, the left menu displays the objects that are directly below the second-level node that is currently being viewed, but also only for the classes specified in menu.ini. The new Membership Application Form class needs an entry in the relevant menu.ini file.

This example uses the Website Interface extension, so either of these settings override files can be edited:

/extension/ezwebin/settings/menu.ini.append.php

OR

/settings/override/menu.ini.append.php

The entries added are shown below.

menu.ini settings

This may not be necessary for all forms if you do not need them to be visible in the top or left menus (for example, if you are just going to link to the form in the body of an article). In our case, we have added the appropriate entries to both the TopIdentifierList setting (objects of these classes are shown in the flat_top menu template at extension/ezwebin/design/ezwebin/templates/menu/flat_top.tpl), and the LeftIdentifiersList setting (objects of these classes are shown in the flat_left menu template at extension/ezwebin/design/ezwebin/templates/menu/flat_left.tpl).

Menu areas

Form view template INI settings

Without an override template, eZ Publish will use the /node/view/full.tpl template to display the form, but that template does not include the elements required to display and process the form properly.

To point eZ Publish to the correct template (which we will create next), edit the override.ini.append.php file for each siteaccess, such as the “eng” siteaccess:

/settings/siteaccess/eng/override.ini.append.php

Add the following entry to the override file:

[full_membership_application_form]
Source=node/view/full.tpl
MatchFile=full/membership_application_form.tpl
Subdir=templates
Match[class_identifier]=membership_application_form