Description: This Form is responsible for creation of the form header and footer. It can not hold form elements. Instead one has to create a form container and put the form elements there. E.g. use FormLayoutContainer or FormVelocityContainer.
This Form is the Component which gets dispatched by the framework. It then dispatches further to the really clicked FormComponent. The Form implements the following phases:
- let all Formelements evaluate the Formrequest
- dispatch to the correct FormComponent
- the dispatched FormComponent may decide to SUBMIT the form, e.g. let all FormComponents validate its input and report error, or taken other actions.
- during the validatition phase each FormComponent can register an action
- after the validation, all actions are applied
- an event is thrown if the form validated or not
FormComponent and FormContainer form the same composite pattern as already used for the core.Component and core.Container, and take notice that the FormComponent itself is also a core.Component!
As a consequence of this, each element which want to live inside of a form must be a FormComponent but has also a Component side to the rendering framework.
The goals of the new form infrastructure are
- to allow complete freedom for layouting forms.
- easy-migration path for existing forms
- easy-usage for developers
- easy-layouting for designers
- allow subworkflows in forms without loosing form input
- allow AJAX features for form elements (completion, on blur etc.)
Some extra care had to be taken to fullfill these requirements and still beeing compliant with the already existing AJAX component replacement.
It was decided that a FormComponent consist of
- Formelement, e.g. input field, radio button, select box, a link!
- Label for the Formelement
- Error for the Formelement
- Example for the Formelement
Multipart and file upload
Since release 6.1 the form infrastructure does also support multipart form data (file uploads). The form switches to the multipart mode as soon as a form element of type FormMultipartItem is added. In this case, all file uploads and form parameters are parsed by the form class and added to the requestParams and requestMultipartFiles maps. If no multipart element is in the form, the normal non-multipart way is used (less overhead, stability).
Therefore it is important to always use the form.getParameter() methods and not the getParameter() methods from the user request directly. Normally you don't have to deal with this because the implemented form elements already take care of this issue.
All submitted files are saved to a temporary location in the userdata/tmp/ directory. During the dispatch phase in evalFormRequest() this files can be access using the getMultipartFilesSet() and getMultipartFile() methods. The files must be moved to another location within the execution of the evalFormRequest() because at the end of the method call, the temporary files will be removed. The temporary files have a random file name, use the getMultipartFileName() to retrieve the original file name.
When using the FileElement this is all already encapsulated, see the documentation there.
Initial Date: 27.11.2006
@author patrickb