PHPlib
 Friday, July 25, 2008  
download | documentation | faq | changelog | resources 

search for in the  

PHPlib ManualPHPlib Manual
Extended FunctionalityExtended Functionality
 TemplateTemplate
 Object Oriented HTML FormsObject Oriented HTML Forms

previousTemplate Examples
Customizing OOH Formsnext

Last updated: Thu, 04 Jul 2002
view this page in Plain HTML

Table of Contents

Using OOH Forms
Customizing OOH Forms

The form class (sometimes called OOH Forms) is a convenience library for dealing with html forms. It provides Javascript and server-side form validation, and is customizable and extensible.

The OOH Forms library consists of five files: oohforms.inc of_checkbox.inc of_radio.inc of_select.inc of_text.inc of_textarea.inc. oohforms.inc automatically includes the others. You may wish to modify this so you can manually include the files for just the form elements you use. Or you may wish to cut and paste the contents of the element files into oohforms.inc to save the overhead of multiple includes. Determining the appropriate configuration of the files for your site is left an exercise for the reader; for most purposes require("oohforms.inc") will suffice.

In general, the structure of a page that uses oohforms is as follows: 

	require("oohforms.inc");         // include the library

	$f = new form;                   // create a form object

	$f->add_element(...);     // set up form elements
	$f->add_element(...);
	$f->add_element(...);

	if ($submitname)                 // Is there data to process?
	  if ($err = $f->validate()) {   // Is the data valid?
	    echo $err;                   // No; Display error
	    $f->load_defaults();  // Load form with submitted data
	  else {
	    /* Process data */           // Data ok; Do something with it
	  }

	$f->start(...);                  // Start displaying form
	$f->show_element(...);    // Show elements
	$f->show_element(...);
	$f->show_element(...);
	$->finish();                     // Finish form

There are obviously many variations on this theme, but that covers the basics. Specific methods are documented below.

Outputs the initial <form> tag and sets up some initial state needed by the class. All of the arguments are optional, though you'll usually want to use at least one in order to get Javascript validation. $jvsname is an arbitrary string used to link the Javascript to the form; if it is empty (the default), no Javascript validation is provided. $method is the HTTP method used to submit the form; default is "POST". $action is the URL that receives the form submission; default is $PHP_SELF. $target is the frame target for the form results; default is _self.

Outputs the any hidden fields that were added to the form, the final </form> tag, then the Javascript validation function (if necessary). $after and $before are both optional; if either is a nonempty string it is output as additional Javascript to be run on submission of the form, either before or after the validation code. Though the order of the arguments may seem counterintuitive, it makes the common case easier to type; in general you'll want to wait until after the validation has taken place to do anything fancy with Javascript. Note that unlike with validation, OOH Forms has no way of giving you server side functionality equivalent to the Javascript you use here.

add_element is used to define the attributes of a particular form element so that the other class methods can use and manipulate it properly. add_element takes exactly one argument: an associate array whose key value pairs are used to define the form element type and it's various attributes. Some of these attributes correspond to html attributes, while others are needed for the value added features of oohforms. The attributes and the syntax and semantics of the values they take are documented below; note that not all element types use all of the attributes

The type of element this is; can be "submit", "hidden", "text", "textarea", "select", "radio", "checkbox", or "file".

A string naming this element. This name will be used as an argument to other methods and will be the name="" value in the generated html (and hence the variable name in PHP). Do not append [] to the name if you want an array valued element; set the multiple attribute instead.

The default value of this form element. If the form element has the multiple attribute set, value can be an array. If the this is a select element, value can refer to either the textual name (label in the options array) or the submission value (value in options).

A flag to tell oohforms to assume this element is array valued. The use of this flag is most straightforward with select elements, but it can be use with text and checkbox elements as well. See the show_element documentation for more information about how oohforms deals with such elements.

Extra html code that is inserted verbatim into the opening element tag. For select elements, the extra html goes into the select tag, not the option tags.

For text elements, used to set the html size attribute that gives the width in characters of the text entry box. For select elements, the size (number of options visible at once) of the selection box. Validation is only performed on select elements if size is set to 1, since select validation doesn't make much sense if you can see multiple options at once. For file elements, the maximum size file upload to accept.

If set for a text element, renders the html as a password element, i.e. entry displays as asterisks.

If set for a submit element, convert to an image element and use the value of src as the source URL for the image.

Used verbatim as the maxlength html attribute in text elements.

If length_e is set, this is the minimum length text element entry accepted by the validator.

If set, validate the text element to assure it has at least minlength characters. The value of length_e is the error string to be used in the event of failed validation.

If set, perform validation on a text, radio, or select element. For a text element, validation assures a match with valid_ regex. radio element validation assures that one of the options in the group has been chosen. select validation only works for select elements with multiple unset and size equal to 1; the validator will not accept the first option of accept menu, assuming that it is some sort of prompt (e.g. "Please select an item"). In all cases, the value of valid_e is the error string used for failed validations.

Regular expression used to validate entry into a test field if valid_e is set. Note that if you must use ^...$ if you want the regex to match the whole entry.

If set, regex matching is case insensitive.

Only used for a checkbox element that does not have multiple set. If checked is set, the element will display as checked.

Used verbatim as the rows= element in a textarea element.

Used verbatim as the cols= element in a textarea element.

Used verbatim as the wrap= element in a textarea element.

Array of options to be displayed in a select element. If the elements of the array are simple values (strings or numbers), they are simply displayed verbatim and used as the value for that particular option. The elements may themselves be associate arrays with keys "label" and "value". In that case, the value of "label" is displayed and the value of "value" is used on submission.

Examples:

	$f->add_element(array("type"=>"text",
	                             "name"=>"foo",
	                             "valid_regex"=>"^[a-z]*$",
	                             "valid_e"=>"Letters only",
	                             "icase"=>1,
	                             "value"=>"bar"));
	$f->add_element(array("type"=>"checkbox",
	                             "name"=>"compress",
	                             "multiple"=>1));
	$f->add_element(array("type"=>"textarea",
	                             "name"=>"comment",
	                             "rows"=>6,
	                             "cols"=>40,
	                             "value"=>""));
	$o = array(array("label"=>"Please Select","value"=>0),
	           array("label"=>"Apple","value"=>1),
	           array("label"=>"Orange","value"=>2),
	           array("label"=>"Pear","value"=>3),
	           array("label"=>"Grape","value"=>4));
	$f->add_element(array("type"=>"select",
	                             "name"=>"menu",
	                             "options"=>$o,
	                             "size"=>1,
	                             "valid_e"=>"Please select a fruit",
	                             "value"=>"apple"));

Outputs the form element named $name. Usually, the second argument is not used. It is always necessary for radio elements and checkbox elements with the multiple attribute set, since many of these may have the same name. It also must be used for submit elements to label the submission button; the value attribute is not used for submit elements. For other elements that may be array valued (notably text elements) multiple calls to show_element will show successive values.

Sets the default value of form elements to the value of the PHP variables with the same name. This is generally used to redisplay a form with the same values which were submitted. The argument is optional; if given it is an array of element names; only these elements ares affected.

Validates a form submission. If all of the elements are valid, return $result, otherwise return the relevant error message (the valid_e or length_e attribute of some form element). $result defaults to false. The second argument is also optional; it is an array of names of elements to validate.

Freezes the form elements whose names are given in the array passed as the argument. If no argument is given, freeze all of the elements. Frozen elements are rendered as plain, static html rather than form widgets. This static rendering is accompanied by appropriate hidden elements to simulate the affect of using the unfrozen version of the element.


User Contributed Notes
Object Oriented HTML Forms
add a note about notes
There are no user contributed notes for this page.


previousTemplate Examples
Customizing OOH Formsnext

Last updated: Thu, 04 Jul 2002

 

PHP Copyright © 2001 The PHPlib Group
All rights reserved.
 		Last updated: Thu Jul 4 15:39:08 2002 IST
Hosted and Maintained by http://www.sanisoft.com