

Packageindex	Classtrees	Modulegroups	Elementlist	Report	XML Files

File: c:/www/apache/doc2//form/form.inc

PHPLib Form Rewrite 2001/03/01 - Form

form

form_commonobject
|
+-- form

Object oriented HTML form generation and validation.

public class form extends form_commonobject

Object oriented HTML form generation and validation.
The form classes provide a way to generate and validate a HTMLform without the need to write a single line of HTML. Serverside and clientside(JavaScript1.2) validation is done automatically. This code is thesuccessor of the OOH Forms. See pages/form/ for examples.A form consists of an object of this class which controls lots of form elements.Form known all HTML form element types plus some compound types:- button- checkbox- combo (text + select box)- date (lots of select boxes)- file- hidden- image- password- radio- select box- submit- text- textarea- tree (select box with options show as a tree)

Authors Ulf Wendel <ulf.wendel@phpdoc.de>

Version $Id: form.inc,v 1.14 2000/12/19 10:39:49 uw Exp $

Direct known subclasses: example_form

Methods inherited from form_commonobject

introspection

Public Method Summary
void	setJSMode([ string $js_mode ]) Sets the JavaScript validation mode.
void	setMethod([ string $method ]) Sets the method used by this form.
boolean	autoloadValues([ mixed $ellist ]) Loads the form with HTTP_[POST\|GET]_VARS.
boolean	setValues(array $values) Sets the value of one element or a group of elements.
void	ValidationOff(mixed $ellist) Public handle to turn default validation off.
void	ValidationOn(mixed $ellist) Public handle to turn default validation on.
string	getStart([ string $js_name, string $method, string $action, string $target ]) Generates the opening HTML form tag, <form>.
void	Start([ string $js_name, string $method, string $action, string $target ]) Generate and print <form>-Tag
string	getFinish([ string $additional_html, mixed $sess ]) Generates the closing HTML form tag and handles the hidden elements.
void	Finish([ string $additional_html, mixed $sess ]) Generate and print closing </form>-Tag.
string	get([ string $js_name, string $method, string $action, string $target, string $additional_html ]) Generate the complete form.
void	show([ string $js_name, string $method, string $action, string $target, string $additional_html ]) Generate and print the complete form.
bool	addElement(array $element_data) Adds an element to the form object.
string	getElement(string $elname, [ string $value ]) Generate and return the html representation of an element.
string	getType(string $elname) Return the type of an element.
mixed	getValue(string $name) Return the current value of an element.
array	validate([ mixed $vallist ]) Validate a form.
boolean	setValidationError(string $name, string $message) Sets the validation error message for of an element.
array	getValidationResult() Returns an array that holds the results of the last validation.
void	freeze([ mixed $flist ]) Freeze an element, frozen elements are drawn in an non editable way.
void	unfreeze([ mixed $flist ]) Thaw out an element.
bool	addJS(string $name, string $code) Adds JavaScript validation code to an element
string	getJS() Returns JavaScript validation code.
array	getElements() Returns an array of all elements.
array	getOptions(mixed $ellist) Return an array of all options of a combo list.
array	getSessionHash() FIXME
boolean	isChecked(string $elname) Is this checkboxobject checked?
string	getNewComboOption(string $name) Returns the latest combo entry of the user
bool	addOption(string $name, string $label, [ string $value ]) Add a new option to a combo
array	getTree(string $ellist) FIXME FIXME
bool	setTree(array $ellist) Set the tree of an treeview element
void	setJSError(string $prefix, string $postfix) Sets the JavaScript error message pre- and postfix text.

Private Method Summary
void	Validation(mixed $ellist, [ boolean $status ]) Controls the default validation of an element.
boolean	setValidator(string $name, string $validator) Sets the name of a custom validation function.
void	showElement(string $elname, [ string $value ]) Return and print an element.
array	getCustomValidators([ mixed $ellist ]) Returns an array of all custom validation functions
string	compressJS(string $code) Removes tabs, spaces and newlines from the given JavaScript code.
void	thawout([ mixed $flist ]) Thaw out an element.
bool	ElementExists(string $name) Checks the existance of a certain element.
boolean	setDefaults(array $defaults) Sets default element attributes.
void	addDefaultAttributes(array &$element_data) Adds default values to an element if they haven't been overriden.
void	getNameTranslationList(mixed $ellist) FIXME
void	getElementnames() FIXME
string	clearCode(string $code) Reformate generated code
boolean	setElementnamePrefix(string $prefix) Sets a global Prefix for element names.
boolean	isMethodAllowed(string $function, string $name, mixed $required_type)
void	list( $eldata, $getvalue_func, $getvalue_fname, $js_validator, $el, $el, $complex, $complex, $js_validator, $custom, $custom, $custom, $js_validator, $js, $js, $js, $js, $js, $js, $js, $js, $eldata, $getvalue_fname, $getvalue_fname) Warning: documentation is missing.
void	setOptions( $ellist) Warning: documentation is missing.

Fields inherited from form_commonobject

$cr_html, $exceptions

Public Field Summary
boolean	$flag_loader Flag indication that you're using the Form Loader.

Private Field Summary
array	$defaults Some default values.
array	$elements Array of all elements.
array	$element_names List of all element names.
string	$element_prefix Global element name prefix.
array	$validation_flags Results of the last validation.
string	$validation_msg String with all error messages.
array	$hidden_elements Array of hidden elements.
array	$radio_elements Array of radio elements.
string	$js_name HTML name attribute of the opening form Tag.
string	$js_mode JavaScript validation mode
string	$js_error_prefix JavaScript error message prefix.
string	$js_error_postfix JavaScript error message postfix.
string	$method Method used in the form.
boolean	$flag_contains_file Flag indicating that a file upload button is in the form.

Public Method Details

setJSMode

public void setJSMode( [ string $js_mode ] )

Sets the JavaScript validation mode.

Parameter

string	$js_mode	`= >>"weak"<<`
	"weak" or "strong", if "strong" validation will be done onChange/onClick otherwise only onSubmit.

Returns

void

setMethod

public void setMethod( [ string $method ] )

Sets the method used by this form.

Parameter

string	$method	`= >>"POST"<<`
	"POST" or "GET"

Returns

void

autoloadValues

public boolean autoloadValues( [ mixed $ellist ] )

Loads the form with HTTP_[POST|GET]_VARS.

Parameter

mixed	$ellist	`= >>""<<`
	of one element or array of elements. An empty string causes a fallback to all elements.

Returns

boolean

setValues

public boolean setValues( array $values )

Sets the value of one element or a group of elements.

Parameter

array	$values
	of values, $values[ name ] = value

Returns

boolean

Throws form_error

ValidationOff

public void ValidationOff( mixed $ellist )

Public handle to turn default validation off.

Parameter

mixed	$ellist
	Name of one element or array of elements.

Returns

void

ValidationOn

public void ValidationOn( mixed $ellist )

Public handle to turn default validation on.

Parameter

mixed	$ellist
	Name of one element or array of elements.

Returns

void

getStart

public string getStart( [ string $js_name, string $method, string $action, string $target ] )

Generates the opening HTML form tag, <form>.

Parameter

string	$js_name	`= >>""<<`
	form name. If empty no JavaScript validation will be done.

string	$method	`= >>"POST"<<`
	method attribute: "POST" or "GET".

string	$action	`= >>""<<`
	action attribute. If empty $PHP_SELF gets used.

string	$target	`= >>""<<`
	target attribute.

Returns

string

HTML form-Tag

Required global variables

string $PHP_SELF

Start

public void Start( [ string $js_name, string $method, string $action, string $target ] )

Generate and print <form>-Tag

Parameter

string	$js_name	`= >>""<<`
	form name. If empty no JavaScript validation will be done.

string	$method	`= >>"POST"<<`
	method attribute: "POST" or "GET".

string	$action	`= >>""<<`
	action attribute. If empty $PHP_SELF gets used.

string	$target	`= >>""<<`
	target attribute.

Returns

void

Required global variables

string $PHP_SELF

getFinish

public string getFinish( [ string $additional_html, mixed $sess ] )

Generates the closing HTML form tag and handles the hidden elements.

Parameter

string	$additional_html	`= >>""<<`
	Optional, additional HTML inserted in front of the generated HTML.

mixed	$sess	`= >>""<<`
	Session Class

Returns

string $html

Finish

public void Finish( [ string $additional_html, mixed $sess ] )

Generate and print closing </form>-Tag.

Parameter

string	$additional_html	`= >>""<<`
	Optional, additional HTML inserted in front of the generated HTML.

mixed	$sess	`= >>""<<`
	Session Class

Returns

void

get

public string get( [ string $js_name, string $method, string $action, string $target, string $additional_html ] )

Generate the complete form.

Parameter

string	$js_name	`= >>""<<`
	form name. If empty no JavaScript validation will be done.

string	$method	`= >>"POST"<<`
	method attribute: "POST" or "GET".

string	$action	`= >>""<<`
	action attribute. If empty $PHP_SELF gets used.

string	$target	`= >>""<<`
	target attribute.

string	$additional_html	`= >>""<<`
	HTML added right before the closing form-Tag

Returns

string

HTML form-Tag

Required global variables

string $PHP_SELF

show

public void show( [ string $js_name, string $method, string $action, string $target, string $additional_html ] )

Generate and print the complete form.

Parameter

string	$js_name	`= >>""<<`
	form name. If empty no JavaScript validation will be done.

string	$method	`= >>"POST"<<`
	method attribute: "POST" or "GET".

string	$action	`= >>""<<`
	action attribute. If empty $PHP_SELF gets used.

string	$target	`= >>""<<`
	target attribute.

string	$additional_html	`= >>""<<`
	HTML added right before the closing form-Tag

Returns

void

Required global variables

string $PHP_SELF

addElement

public bool addElement( array $element_data )

Adds an element to the form object.

Parameter

array	$element_data

Returns

bool $ok

Throws form_error

getElement

public string getElement( string $elname, [ string $value ] )

Generate and return the html representation of an element.

Parameter

string	$elname
	name

string	$value	`= >>""<<`
	value, only used with radio - FIXME

Returns

string

HTML

Throws form_error

getType

public string getType( string $elname )

Return the type of an element.

Parameter

string	$elname

Returns

string $type

Throws form_error

getValue

public mixed getValue( string $name )

Return the current value of an element.
Use the function within your custom validation functions.

Parameter

string	$name
	element name

Returns

mixed $value

Throws form_error

validate

public array validate( [ mixed $vallist ] )

Validate a form.

Parameter

mixed	$vallist	`= >>""<<`

Returns

array

($error_msg, $error_flags)

setValidationError

public boolean setValidationError( string $name, string $message )

Sets the validation error message for of an element.

Parameter

string	$name
	element name

string	$message

Returns

boolean $ok

Throws form_error

See Also getValidationResult(), validate()

getValidationResult

public array getValidationResult( )

Returns an array that holds the results of the last validation.

Returns

array

($error_msg, $error_flags)

See Also setValidationError(), validate()

freeze

public void freeze( [ mixed $flist ] )

Freeze an element, frozen elements are drawn in an non editable way.
A user can't change the value of an frozen element.

Parameter

mixed	$flist	`= >>""<<`

Returns

void

unfreeze

public void unfreeze( [ mixed $flist ] )

Thaw out an element.

Parameter

mixed	$flist	`= >>""<<`
	of one element or list of elements to unfreeze. An empty string causes a fallback to all elements.

Returns

void

addJS

public bool addJS( string $name, string $code )

Adds JavaScript validation code to an element
FIXME

Parameter

string	$name
	name of the element

string	$code
	JavaScript code

Returns

bool $ok

Throws form_error

getJS

public string getJS( )

Returns JavaScript validation code.

Returns

string $code

JavaScript validation code

Throws form_error

getElements

public array getElements( )

Returns an array of all elements.

Returns

array $elements

[ name ] = name

getOptions

public array getOptions( mixed $ellist )

Return an array of all options of a combo list.
Comboboxes expand their option list. Take care that you savethe expanded option list so that you can reload the newoption list after the form was submittet.FIXME getOptions()

Parameter

mixed	$ellist
	String with the name of one element or a list of elements.

Returns

array $options

Throws form_error

getSessionHash

public array getSessionHash( )

FIXME
Returns an array with elname => value pairs, that can be usedto be stored in a session. new_assistant needs this

Returns

array $session_hash

isChecked

public boolean isChecked( string $elname )

Is this checkboxobject checked?

Parameter

string	$elname
	name

Returns

boolean

getNewComboOption

public string getNewComboOption( string $name )

Returns the latest combo entry of the user

Parameter

string	$name
	element name

Returns

string $html

addOption

public bool addOption( string $name, string $label, [ string $value ] )

Add a new option to a combo

Parameter

string	$name

string	$label

string	$value	`= >>""<<`
	= ""

Returns

bool $ok

See Also getNewComboOption(), SetOptions(), getOptions()

getTree

public array getTree( string $ellist )

FIXME FIXME
Returns the tree for a certain value of an treeview elementIt's just implementet to make the api complete

Parameter

string	$ellist
	\|array $ellist

Returns

array $trees

setTree

public bool setTree( array $ellist )

Set the tree of an treeview element
Helpful with dynamically changing trees

Parameter

array	$ellist

Returns

bool $ok

Throws form_error

setJSError

public void setJSError( string $prefix, string $postfix )

Sets the JavaScript error message pre- and postfix text.

Parameter

string	$prefix

string	$postfix

Returns

void

See Also $js_error_prefix, $js_error_postfix

Private Method Details

Validation

private void Validation( mixed $ellist, [ boolean $status ] )

Controls the default validation of an element.
The new forms provide a way to validate depencencies between form elements.You may define a dependencie validation method for any element(attribute: validator). It gets called in the very first lines ofvalidate() and controls the default validators by turning them on/offfor certain elements using validation().

Parameter

mixed	$ellist
	Eigther the name of one element of an array of elements: $ellist [ name ] = events.

boolean	$status	`= >>false<<`
	The default of false turns off the validation, true turns it on.

Returns

void

See Also ValidationOn(), ValidationOff()

setValidator

private boolean setValidator( string $name, string $validator )

Sets the name of a custom validation function.

Parameter

string	$name
	element name

string	$validator
	name of validation function

Returns

boolean

Throws form_error

showElement

private void showElement( string $elname, [ string $value ] )

Return and print an element.

Parameter

string	$elname
	name

string	$value	`= >>""<<`
	value, only used with radio - FIXME

Returns

void

Throws form_error

getCustomValidators

private array getCustomValidators( [ mixed $ellist ] )

Returns an array of all custom validation functions

Parameter

mixed	$ellist	`= >>""<<`

Returns

array $validators

$k => $custom_function

compressJS

private string compressJS( string $code )

Removes tabs, spaces and newlines from the given JavaScript code.
Warning: do not use this function with user supplied code.The function replaces most tabs and spaces with an empty string beforeit starts to remove some newlines. The resulting code is usually15-25% shorter than the orginial code.

Parameter

string	$code
	code snippet

Returns

string

compressed code

thawout

private void thawout( [ mixed $flist ] )

Thaw out an element.

Parameter

mixed	$flist	`= >>""<<`
	of one element or list of elements to unfreeze. An empty string causes a fallback to all elements.

Returns

void

ElementExists

private bool ElementExists( string $name )

Checks the existance of a certain element.

Parameter

string	$name
	name of the requested element

Returns

bool $ok

setDefaults

private boolean setDefaults( array $defaults )

Sets default element attributes.
You can use this function to define default values forelements.

Parameter

array	$defaults
	$default [ attribute ] = value

Returns

boolean $ok

Throws form_error

addDefaultAttributes

private void addDefaultAttributes( array &$element_data )

Adds default values to an element if they haven't been overriden.

Parameter

array	&$element_data

Returns

void

getNameTranslationList

private void getNameTranslationList( mixed $ellist )

FIXME

Parameter

mixed	$ellist

Returns

void

getElementnames

private void getElementnames( )

FIXME

Returns

void

clearCode

private string clearCode( string $code )

Reformate generated code

Parameter

string	$code

Returns

string $code

setElementnamePrefix

private boolean setElementnamePrefix( string $prefix )

Sets a global Prefix for element names.

Parameter

string	$prefix

Returns

boolean

isMethodAllowed

private boolean isMethodAllowed( string $function, string $name, mixed $required_type )

Parameter

string	$function
	Name of the function that calls this method

string	$name
	Name of a form element

mixed	$required_type

Returns

boolean $ok

Throws form_error

list

private void list( $eldata, $getvalue_func, $getvalue_fname, $js_validator, $el, $el, $complex, $complex, $js_validator, $custom, $custom, $custom, $js_validator, $js, $js, $js, $js, $js, $js, $js, $js, $eldata, $getvalue_fname, $getvalue_fname )

Warning: documentation is missing.

Parameter

	$eldata
	Warning: documentation is missing.

	$getvalue_func
	Warning: documentation is missing.

	$getvalue_fname
	Warning: documentation is missing.

	$js_validator
	Warning: documentation is missing.

	$el
	Warning: documentation is missing.

	$el
	Warning: documentation is missing.

	$complex
	Warning: documentation is missing.

	$complex
	Warning: documentation is missing.

	$js_validator
	Warning: documentation is missing.

	$custom
	Warning: documentation is missing.

	$custom
	Warning: documentation is missing.

	$custom
	Warning: documentation is missing.

	$js_validator
	Warning: documentation is missing.

	$js
	Warning: documentation is missing.

	$js
	Warning: documentation is missing.

	$js
	Warning: documentation is missing.

	$js
	Warning: documentation is missing.

	$js
	Warning: documentation is missing.

	$js
	Warning: documentation is missing.

	$js
	Warning: documentation is missing.

	$js
	Warning: documentation is missing.

	$eldata
	Warning: documentation is missing.

	$getvalue_fname
	Warning: documentation is missing.

	$getvalue_fname
	Warning: documentation is missing.

Returns

void

setOptions

private void setOptions( $ellist )

Warning: documentation is missing.

Parameter

	$ellist
	Warning: documentation is missing.

Returns

void

Public Field Details
$flag_loader
public boolean $flag_loader >>`true`<< Flag indication that you're using the Form Loader. addElement() will call form_elements_loader() if the flag is set to true.It's strongly recommended that you use the Form Loader unless you'reusing the Zend Cache or a similar product.

Private Field Details
$defaults
private array $defaults >>`array( # text element defaults "textsize" => 0, "textmaxlength" => 0, # file element defaults "filesize" => 0, # image element defaults "imageborder" => 0, # select objects "selectintro" => "", "selectintro_e" => "", # HTML CSS defaults "cssid" => "", "cssclass" => "", "cssstyle" => "" )`<< Some default values.
See Also	setDefaults()

$elements
private array $elements >>`array()`<< Array of all elements.

$element_names
private array $element_names >>`array()`<< List of all element names.

$element_prefix
private string $element_prefix >>`""`<< Global element name prefix. In multipage forms a global element name prefix can beused to avoid name clashes.
See Also	setElementnamePrefix()

$validation_flags
private array $validation_flags >>`array()`<< Results of the last validation.
See Also	validate(), setValidationError(), getValidationResult(), $validation_msg

$validation_msg
private string $validation_msg >>`""`<< String with all error messages.
See Also	validate(), setValidationError(), getValidationResult(), $validation_flags

$hidden_elements
private array $hidden_elements >>`array()`<< Array of hidden elements. Hidden elements are treated different than in the old oohforms. Now you cangive a hidden element an html name (attribute name) and an alias name (elname)to access the element. That caused the introduction of some translationtables.

$radio_elements
private array $radio_elements >>`array()`<< Array of radio elements.

$js_name
private string $js_name >>`""`<< HTML name attribute of the opening form Tag. If no name is given no JavaScript validation will be done.

$js_mode
private string $js_mode >>`"strong"`<< JavaScript validation mode Form knows two kinds of JavaScript validation: "strong" and "weak"."strong" means that validation will be performed onChange/onClick,"weak" stands for onSubmit.

$js_error_prefix
private string $js_error_prefix >>`"There're errors in the form: \n\n"`<< JavaScript error message prefix. Prefix displayed in front of the errors in a JavaScript alert box.
See Also	$js_error_postfix, setJSError()

$js_error_postfix
private string $js_error_postfix >>`"\n\nPlease correct the input."`<< JavaScript error message postfix. Postfix displayed right after the errors in a JavaScript alert box.
See Also	$js_error_prefix, setJSError()

$method
private string $method >>`"POST"`<< Method used in the form.
See Also	Start(), autoloadValues()

$flag_contains_file
private boolean $flag_contains_file >>`false`<< Flag indicating that a file upload button is in the form.

PHPDoc 1.0beta

PHPLib Form Rewrite 2001/03/01 - Form

form

public class form extends form_commonobject

Methods inherited from form_commonobject

Public Method Summary

setJSMode([ string $js_mode ])

setMethod([ string $method ])

autoloadValues([ mixed $ellist ])

setValues(array $values)

ValidationOff(mixed $ellist)

ValidationOn(mixed $ellist)

getStart([ string $js_name, string $method, string $action, string $target ])

Start([ string $js_name, string $method, string $action, string $target ])

getFinish([ string $additional_html, mixed $sess ])

Finish([ string $additional_html, mixed $sess ])

get([ string $js_name, string $method, string $action, string $target, string $additional_html ])

show([ string $js_name, string $method, string $action, string $target, string $additional_html ])

addElement(array $element_data)

getElement(string $elname, [ string $value ])

getType(string $elname)

getValue(string $name)

validate([ mixed $vallist ])

setValidationError(string $name, string $message)

getValidationResult()

freeze([ mixed $flist ])

unfreeze([ mixed $flist ])

addJS(string $name, string $code)

getJS()

getElements()

getOptions(mixed $ellist)

getSessionHash()

isChecked(string $elname)

getNewComboOption(string $name)

addOption(string $name, string $label, [ string $value ])

getTree(string $ellist)

setTree(array $ellist)

setJSError(string $prefix, string $postfix)

Private Method Summary

Validation(mixed $ellist, [ boolean $status ])

setValidator(string $name, string $validator)

showElement(string $elname, [ string $value ])

getCustomValidators([ mixed $ellist ])

compressJS(string $code)

thawout([ mixed $flist ])

ElementExists(string $name)

setDefaults(array $defaults)

addDefaultAttributes(array &$element_data)

getNameTranslationList(mixed $ellist)

getElementnames()

clearCode(string $code)

setElementnamePrefix(string $prefix)

isMethodAllowed(string $function, string $name, mixed $required_type)

list( $eldata, $getvalue_func, $getvalue_fname, $js_validator, $el, $el, $complex, $complex, $js_validator, $custom, $custom, $custom, $js_validator, $js, $js, $js, $js, $js, $js, $js, $js, $eldata, $getvalue_fname, $getvalue_fname)

setOptions( $ellist)

Fields inherited from form_commonobject

Public Field Summary

$flag_loader

Private Field Summary

$defaults

$elements

$element_names

$element_prefix

$validation_flags

$validation_msg

$hidden_elements

$radio_elements

$js_name

$js_mode

$js_error_prefix

$js_error_postfix

$method

$flag_contains_file

Public Method Details

setJSMode

setMethod

autoloadValues

setValues

ValidationOff

ValidationOn

getStart