The Form module

Introduction

The TIP_Form module provides a generic way to build forms using the TiP framework. It is heavely based on the HTML_QuickForm PEAR package.

The form is automatically generated by scanning the field structure of the TIP_Data object.

Despite of the common TiP way to manage things (that is concept separation: style on the left and logic on the right), the form generation does not follow religiously this way. The HTML_QuickForm package generates HTML, and so the logic (PHP) generates style (HTML). Anyway, a number of parameters can be configured to allow a decent level of form customization.

How to generate a form

Usually the form is automatically created by some common action, such as edit and add, that call the TIP_Content::form() method. In some situations, however, you can force a form generation by using special tags, such as the add tag in the TIP_Comments module.

How to customize a form

A lot of options can be configured by using the field comments availables on the database server. Simply use phpMyAdmin (or anyway you fill comfortable with) to put some parameter in the comments of a field. Here is a sample string to put in the comments:

widget=picture|widget_args=autoresize|rules=maxpicturesize(80 80)

This parameters should be specified in the form parameter1=value1|parameter2=value2|.... This means the parameter names and values cannot contain the | character.

• widget=TYPE
  The type of widget to construct. TYPE may be text, password, enum, set, textarea, date, picture or hierarchy. If not specified, the widget type is guessed from the field type: usually will default to text.
  The set widget is a list of boolean flags and will be rendered as a series of checkboxes.
  The enum widget is a single choice between different options: if the choices are more than 3, the widget will be rendered as a select group, otherwise will be a series of optionboxes.
• widget_args=ARGS
  Optional arguments to pass to the widget callback (that is the method that builds the widget). This is obviously a widget dependent value and it is not always used. Below, the explanation splitted on a per-widget basis: consult the form.php source for further, and probably more updated, details.
  • widget=hierarchy
    widget_args=MODULE, that is the id of the TIP_Content module to use to build this hierarchy. If not specified, the id is got from the configuration options.
  • widget=picture
    On widget_args=autoresize, TIP_Form automatically resizes big pictures to fit into the maximum width and height: the aspect ratio is always retained. If widget_args is not specified, pictures bigger than what expected simply raise an error and are not accepted.
  • widget=textarea (or if the field type is TEXT or similar)
    widget_args=FILTERS, that is a comma separated list of filters to use for rendering this Text_Wiki. A typical example of widget_args could be:
    widget_args=Blockquote,Strong,Emphasis,List,Tt
    If not specified, only the base rules are used. These base rules are always applied and should not be specified: Prefilter, Break, Paragraph and Tighten.
    • Heading: allow header elements (+ first header, ++ second header, ...)
    • Toc: generate a table of contents based on the headers ([[toc]])
    • Horiz: draw an horizontal rule (----)
    • Blockquote: enable the use of citations (> text to cite)
    • List: enable numbered and bullet lists (# numbered element, * bullet list)
    • Deflist: enable definition lists (: item1 : description)
    • Table: allow the rendering of tables (|| first cell || second cell ... ||)
    • Center: allow to center paragraphs (= centered text)
    • Url: enable the use of inline URLs (http://www.entidi.com/)
    • Strong: allow strong text (**strong text**)
    • Emphasis: allow emphasis text (//emphasis text//)
    • Tt: allow teletype (monospaced) text ({{teletype text}})
    • Revise: enable revised feature (@@--- deleted text@@ @@+++ inserted text@@)
• category=IMPORTANCE
  IMPORTANCE may be required, suggested or optional: this is used to set the required constraint (if category is required) or to visually highlight a suggested field, if the form template support it.
• rules=RULES
  RULES may be comma separated list of rules (in the format rule(format),...) that must be satisfied to validate this field. The format fragment is optional and should be omitted for rules that don't need any format parameter. For instance, in rules=email,maxlength(40), the email rule doesn't have any format.
  For rules that need more than one parameters, such as rangelength and mimetype, you must separate the parameters with a space, as in rule=rangelength(10 20). This has the disadvantage that you cannot embed spaces in format (nor commas, because used to separate the rules): take this in mind while using regular expression based rules.
  Some rules, such as numeric required date and maxlength, are automatically generated when needed and there is no need to specify them.
  Any valid HTML_QuickForm rule is allowed:
  • required: field required. Automatically set by TiP if the field is in the required category
  • maxlength(max): maximum field length. Automatically set by TiP for text and password widgets
  • minlength(min): minimum field length.
  • rangelength(min max): check the field length is between min and max
  • regex(regular_expression): check the field content against the specified regular expression
  • email: check if the field is a valid email expression
  • unique(field): the inserted value must be unique in the column field of the form table. The only exception is if the found row has the same id of the row edited in the form
  • lettersonly: the field must contain only letters
  • alphanumeric: the field must contain only letters and numbers
  • numeric: the field must be a number: automatically set by TiP for numeric fields
  • nopunctuation: the field must not contain punctuation character
  • nonzero: the field must be a number not starting with 0
  • uploadedfile: required file upload
  • maxfilesize(maxsize): the uploaded file size must not exceed the given number of bytes maximum file size
  • mimetype(mime1 mime2 ...): a space separated list of allowed mime types in file uploads: the mime type is sent by the browser, so don't trust it
  • filename(regex): the file name of the file to upload is checked against the specified regular expression
  • minimagesize(width height): the uploaded image size (as returned by getimagesize) must be greather than width and height
  • maximagesize(width height): the uploaded image size (as returned by getimagesize) must be less than width and height

Technical details

Whenever TIP_Form::run() method is called on a TIP_Form instance, the following steps are performed:

• The field structure is acquired using TIP_Data::getFields()
• The HTML_QuickForm form is initialized using the passed-in options
• Some common element is added to the form, such as the header and the hidden data to identify the form action
• The acquired field structure is carefully scanned and the corresponding elements are appended to the form
• If no default values are provided in the passed-in options, a collection of default values is generated using the acquired field structure as template
• The form is validated
• The pending uploads (if any) are executed: this must be done after the validation so the files are checked before the uploading
• The form is processed, that is on succesful validation the requested operation is performed (add, edit or delete) and the form is freezed otherwise the error message is set and the form reshown
• Button elements are appended after the form processing because (probably) there must be different buttons for processed or not processed forms
• Finally the form is rendered

Althought this list representation seems quite simple, the form generation is a really complex task.