Packages » Package freeform » Class Form

Class Form

Declaration:
<? class Form ?>

Description:
The Form class serves to gather information about the form fields and to display them in documents. Form will be considered valid if all input from user is validated. The form is considered submitted if all its fields are present in the request. Normally the action that processes the form can be called with all parameters correctly passed from the request, in such case it will detect it was submitted and perform its operation. Doing so the same action that displays form can be called as, for example, a remote service. The form detects it is a valid submisiion by the fact that all fields pass validation. The form's lifecycle is as follows:
  1. The owning action instantiates the form and constructs its fields, passing them the default values
  2. The owning action calls the isSubmitted() method of the form which will detect the fact that all input is correct and return true or false as appropriate.
  3. Based on that the action can check the consistency of the submitted data and display results, forward or prompt to correct input.


The form has a way to carry parameters between requests - using the setParameter() method. Such parameters will be available on subsequent request because they will be included as hidden fields. By default all forms will be submitted with the POST method and all forms will have enctype='multipart/form-data', so they are ready to upload files. Each uploaded file in a request will be represented by the UploadedFile instance. However, you can specify which HTTP method to use in the form constructor. The form upon validation will set the offending field values to NULLs - note how this differs from the values submitted by users - empty fields are carried as empty strings. Note that HTML forms must render a special hidden fields of value '' for checkboxes since browsers DO NOT SEND ANYTHING when checkbox is unchecked. In such case the form will get never 'submitted' on the server side. Also note that you cannot trust any field values unless you are sure that the form was submitted. If you use field values and validate them before the call to Form::isSubmitted(), the result of validation can be wrong and the value will be not the value submitted by user. This is because the form can make any assumptions on it being submitted only after all fields have been added to it; only then it copies field values from the request. After that it starts validating field values and, if it fails, the field value is set to NULL. In short, the call to isSubmitted() signals the form that all its fields have been added. Also note that you have to display all the fields you have added to the form on the page, otherwise the form will never get submitted. The best place to construct the form is the Action's onInit() method. The best place to check the validity of submission is the process() method.

Authors:
  • Dennis Popel

Methods:
  • __construct()
    Create new form with no fields.
  • addField()
    Add a field to this form
  • getField()
    Gets an input field by name
  • getFieldValue()
    Returns a particular field's value. A shortcut to Form::getField($fieldName)->getValue()
  • getFieldValues()
    Returns an array of fieldName=>fieldValue pairs
  • getFields()
    Get all fields of the form as an array of name=>InputField pairs
  • getLocation()
    Get the location of the action that will get executed when the form is submitted
  • getMethod()
    Get the HTTP request method that will be used to submit the form's data.
  • getParameters()
    Return all form parameters as an array of name=>value pairs.
  • isSubmitted()
    The form is submitted if all fields were passed from the client. It means that for a form to be submitted each its field must be present in the request.
  • isValid()
    Returns true if all fields are valid. Note that a form is considered valid if it has not been submitted, regardless of actual field values.
  • isValidSubmission()
    This function is the shorthand for simple actions that are interested in the valid submissions of the form, i.e., they do not differentiate invalid input and consider it as a non-submitted state.
  • removeField()
    Remove filed for this form
  • setFieldValues()
    Set field values. You can use this to set the default values of the fields in one call
  • setLocation()
    Set the location of the action that will get executed when the form is submitted
  • setParameter()
    Set a parameter for this form. Form's parameters will be available on subsequest request of the action that gets executed upon the form submission. In HTMLDocument these values will be appended as hidden input fields.
  • setParameters()
    Set multiple parameters in one call