How to Create eZ Publish Forms
Wednesday 19 December 2007 11:44:00 am
This article is part of the eZ Publish “How to” series and provides a step-by-step guide to creating a custom form for an eZ Publish website. To integrate with other examples in this series, this article focuses on the creation of a membership application form for the “eZ Tennis Club” website.
The procedures in this article apply to eZ Publish 3.10.0 with the Website Interface, although the overall principles should also apply to other versions of eZ Publish with and without the Website Interface.
Objects and information collection
There are two methods in eZ Publish to collect and process information from site visitors:
Information collection: creating forms using objects with attributes marked as information collectors
This method uses the “information collection” features of eZ Publish. The most obvious example of this is the contact form (see below) present in a standard Website Interface installation.
With this approach, you create an eZ Publish object that displays as a form to visitors. When visitors fill in the form, new eZ Publish objects are not created. Instead, the information is stored in a separate part of the system and, if configured to do so, emailed to a recipient. This tends to be the method of choice when the user’s input is not made public (for example, in contact forms); and when user responses are collected together for display purposes (for example, in polls).
Contact form, based on the Feedback form object
This article goes through an example with the information collection method. The image below (click to view the full-size image) is a road map for the collected information form functions. It is a useful outline to consult when creating your own forms and when following along in this article.
Collected information form functions road map
Enabling users to create objects
Under this method, the user’s input becomes part of the website as an object in the eZ Publish content node tree. An example of this is creating a new Comment object beneath an existing Article object (to be displayed when visitors view the article). For this to happen, the user must have the appropriate permissions to create the object at a given location within the content structure. Some other examples of this method are the Forum topic and Forum reply objects within an eZ Publish forum.
This approach may use eZ Publish workflows so that a site administrator must approve the user's object before it is visible on the website.
The table below outlines some of the characteristics of each method and is useful for readers who want to explore eZ Publish's features a bit more.
| Enabling users to create objects | Information collection | |
|---|---|---|
| Concept | User fills in a form that becomes a new object in the eZ Publish content structure. | User fills in a form, but this does not become a new object in the eZ Publish content structure - instead, the form is handled by eZ Publish's information collection modules and features. |
|
Examples basic functions |
- Article comments - Forum topics and replies |
- Feedback forms ("contact us" forms) - Polls |
| Datatypes (see the Reference documentation on datatypes) |
Class for the object does not use information collector datatypes. This means: - More datatype options - Possible to use custom datatypes |
Class for the object uses information collector datatypes. This means: - Limited datatype options - Use of custom datatypes is more difficult. One method for dealing with this limitation is to pre-process form input in a custom edit template and then encode the input into a Text line datatype. |
| Permissions | Set via user and user group permissions in the Administration Interface. | May use permissions, although anonymous access can also be defined in settings in collect.ini. |
| What happens within eZ Publish? | A new object (or object awaiting approval) is created in the content node tree. | No new object is created in the content node tree. Instead, a new entry is made in the collected information area under the Setup tab in the Administration Interface. |
| Actions | Can be used in workflow processes. | Option to send email showing information collected (set in collect.ini). |
| Fetch functions - how can I access and use the data collected? |
Normal eZ Publish content fetch functions - a rich range of access and sorting possibilities. |
A limited range of fetch functions: - collected_info_collection - collected_info_count - collected_info_count_list Some of the typical object access and sorting possibilities are unavailable in fetch functions for collected information. |
| Templates | Standard eZ methods, using edit and view templates, or create your own custom edit and view templates. | Expect to have to make your own template to view and edit the form. This can be done using elements from the Poll and Feedback form templates. |
Creating a custom form
In this article, I will walk you through creating a custom membership application form on the eZ Tennis Club website.
The form will collect the following information from site visitors, storing it on the site and emailing it to a specified email address:
- Given name
- Surname
- Date of birth
- Phone number
- Email address
- Postal address
- Opt-in specifications about receiving certain club information
- Open-ended questions or comments
When we are done creating the form, it should look like this:
Final membership application form