form

Please see Core Concepts - Forms for an in-depth discussion about this tag.

Parameters

Apart from the parameters listed below, any parameters given to this tag will be passed on unchanged to the HTML <form> tag generated by this Couch tag. Thus, for example, if you wish to style inline the form, simply set the style parameter of this tag and the resulting HTML form will be passed on the style.

  • name
  • method
  • action
  • separator
  • anchor

name

The name of the form.

method

Method of form submision. Can be either get or post. If skipped, get is assumed.

action

The script handling the form submission. Normally you do not require to set this parameter because this task is handled by Couch.

separator

If the form fails to validate, the names of each failed fields, along with their error messages, are concatanated using a '|' pipe character to get a single string and this string is placed in a variable named k_error. You can change the default pipe separator to any other character by setting this parameter.

anchor

To understand this parameter, suppose a form is created somewhere at the bottom of a web page and requires the user to scroll down the page to reach it. Upon submission of this form, the page is reloaded and in doing so the the form seems to disappear because the refreshed page shows the top region and it will again need scrolling to reach the form. This will cause the user to miss any feedback (error or success messages) that might have been added to the form.
By setting the anchor parameter to '1', Couch adds an HTML anchor ('#') to the form so that the reloaded page scrolls back to the top of the form, thus mitigating the mentioned problem.

Variables

  • k_success
  • k_error

k_success

If the form successfully validates, the names and values of each fields are concatenated using a '\n' newline character to get a single string and this string is placed in a this variable.

k_error

If the form fails to validate, the names of each failed fields along with their error messages are concatenated using a '|' pipe character to get a single string and this string is placed in this variable.

In addition to the two above mentioned variables, the values of the fields are also made available individually by setting discrete variables for each field. The names of the variables, however, differ between the success and error conditions.
Suppose a form has two fields named name and password. Upon successful validation of both fields, two variables named after the two fields will get set - frm_name and frm_password. Each will contain the value submitted through them.
However, if any of the fields fail to validate, variables representing only those failed fields will get set. Suppose the password field is the one that fails. In this case a variable named k_error_password will get set. This variable will contain the error message set for the validating condition.