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)

AuthorsUlf 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

See Also autoloadValues(), $method

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

See Also Validation()

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

See Also Validation()

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
See Also getStart(), getFinish()

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
See Also getStart(), getFinish()

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

See Also freeze()

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
See Also getJS()

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

See Also freeze()

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
See Also $defaults

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

See Also $element_prefix

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.

Packageindex Classtrees Modulegroups Elementlist Report XML Files
PHPDoc 1.0beta