Packageindex Classtrees Modulegroups Elementlist Report XML Files
 
File: c:/www/apache/doc2//form/form_element.inc
PHPLib Form Rewrite 2001/03/01 - Form

form_element

form_commonobject
   |
  +-- form_element

Superclass of all form elements.

 

public abstract class form_element extends form_commonobject

Superclass of all form elements.

AuthorsUlf Wendel <uw@netuse.de>
Version$Id: form_element.inc,v 1.5 2000/12/12 01:37:33 uw Exp $
 
Direct known subclasses: form_element_buttonobject, form_element_checkobject, form_element_selectobject, form_element_date, form_element_hidden, form_element_textobject, form_element_tree

Methods inherited from form_commonobject
introspection

Public Method Summary
void

form_element(array $element_data, int $method, [ string $form_name, string $js_mode ])

Creates a new form element.
mixed

getValue()

Returns the value of an element.
string

getType()

Returns the type of this element.
boolean

isButton()

Returns true if the element is a button, otherwise false
string

getValidator()

Returns the name of the custom validation function.
boolean

setValidator(string $validator)

Sets the name of the custom validation function.
void

freeze()

Freeze the form element.
void

unfreeze()

Thaw out the object
string

get([ string $value ])

Returns the HTML code of the element.
string

validate()

Returns the result of the (serverside) validation.
boolean

react(mixed $events, [ boolean $status ])

Defines the events that will be validated.
void

setValue(mixed $value)

Sets the value of the form element.
array

getJS([ boolean $complex ])

Returns JavaScript validation code.
string

getName()

Returns the HTML/JavaScript name of the element.
bool

isHidden()

Is this a hidden element?

Private Method Summary
void

setup()

Kind of a constructor of a derived form element.
boolean

checkConfiguration(array $element_data)

Checks the data used to initialize the element.
void

thawout()

Alias for unfreeze().
string

getfrozen([ string $value ])

Returns thr HTML code of the frozen element.
void

show([ string $value ])

Print version of get().
string

validateLength([ mixed $value ])

Validate the length of the input value.
string

validateRegEx([ mixed $value ])

Compare the element value with the specified RegExp.
boolean

doValidation(string $event)

Validate this event?
string

getJSonActivation()

Return a JavaScript onChange attribute if strong Javascript validation is active
string

getCommonHTMLAttributes()

Returns a HTML string with the html attributes shared by all element.
string

getFrozenHiddenElement([ mixed $value ])

Returns the element as a HTML hidden field.
string

getFrozenTable([ boolean $border, mixed $value ])

Returns the elements as a HTML table.
array

getJSvalue()

JavaScript function used to get the value of the element.
array

getExtraJS()

Returns additional JavaScript required by some complex form elements.

Fields inherited from form_commonobject
$cr_html, $exceptions

Public Field Summary
boolean

$flag_config_ok

Private Field Summary
string

$elname

Alias name of the element.
string

$name

HTML name attribute of the element.
string

$value

Value of the element.
string

$additional_html

Additional HTML attributes.
boolean

$frozen

Is the element frozen?
string

$class

HTML/CSS class attribute.
string

$id

HTML/CSS id attribute.
string

$style

HTML/CSS style attribute
array

$shared_required_fields

List of required fields every element needs and their type.
array

$required_fields

List of required fields provided by a derived class.
array

$shared_optional_fields

List of optional fields and their type.
array

$optional_fields

List of optional fields provided by a derived class.
string

$method

Method (POST|GET) used in the form.
array

$val_events

Check for ... errors.
string

$js_mode

JavaScript validation mode.
string

$form_name

Name of the form that contains the element.
string

$validator

Name of a custom validation function provided by the user.
string

$js_validator

Custom JavaScript validator.

Public Method Details

form_element

public void form_element( array $element_data, int $method, [ string $form_name, string $js_mode ] )
  Creates a new form element.
The form object uses this constructor to setup any form element.Derived constructurs are not called by the form object. If you needsome kind of setup in any of the derived form element classes overridesetup(). Setup() gets always called by form_element().

Parameter
array $element_data
Array describing the form element
int $method
erpreted as "GET".
string $form_name = >>""<<
HTML name attribute of the form tag.
string $js_mode = >>""<<
Optional, JavaScript validation mode. If set to
"strong" (case insensitive) each element gets checked
when changed (onChange/onClick) and when the form gets submitted (onSubmit).
All other values start JavaScript validation with "onSubmit".
Returns void

getValue

public mixed getValue( )
  Returns the value of an element.

Returns mixed $value

getType

public string getType( )
  Returns the type of this element.

Returns string $type

isButton

public boolean isButton( )
  Returns true if the element is a button, otherwise false

Returns boolean $is_button

getValidator

public string getValidator( )
  Returns the name of the custom validation function.

Returns string $validator
See Also setValidator()

setValidator

public boolean setValidator( string $validator )
  Sets the name of the custom validation function.

Parameter
string $validator
Returns boolean $ok
Throws form_error
See Also getValidator()

freeze

public void freeze( )
  Freeze the form element.

Returns void

unfreeze

public void unfreeze( )
  Thaw out the object

Returns void

get

public abstract string get( [ string $value ] )
  Returns the HTML code of the element.

Parameter
string $value = >>""<<
The value is only used with radio buttons.
If the given value is equal to the value of the
element when it was defined, the radio gets selected.
Returns string $html

HTML code of the element.
See Also getfrozen(), show()

validate

public abstract string validate( )
  Returns the result of the (serverside) validation.

Returns string

Error message if there is an error
See Also validateLength(), validateRegEx(), doValidation()

react

public boolean react( mixed $events, [ boolean $status ] )
  Defines the events that will be validated.
You can tell every (default) validator which "events"will be validated. This gives you detailed controlon a default validator in you dependencie validators."Event" stands for some properties of an element (length, valid, intro)as well as the used JavaScript event handler (js_onsubmit,js_onchange) for the element.Using react() you can for example switch off the validationof the RegExp (valid_e, valid_regexp) writing:$formelement->react("valid", false);

Parameter
mixed $events
Eighter a string with the name
of one "event" or an array of "events".
Known "events" are: all, length, valid, intro,
js_onsubmit, js_onchange. "length" controls
length_e, minlength and maxlength, "valid" controls
valid_e and valid_regexp and "intro" controls "intro", "intro_e".
"js_onsubmit" and "js_onchange" referr to the JavaScript
event handler.
boolean $status = >>true<<
Optional, if set to true the specified "events" will be validated,
otherwise validation is turned off (default: true = on)
Returns boolean $ok

Returns false if no valid events where found.
Throws form_error
See Also $val_events

setValue

public void setValue( mixed $value )
  Sets the value of the form element.

Parameter
mixed $value
Returns void

getJS

public array getJS( [ boolean $complex ] )
  Returns JavaScript validation code.
See form_js_simple.js and form_js_complex.js for details on the JavaScriptvalidation code. This function build a record to "feed" the JavaScript formobject.

Parameter
boolean $complex = >>false<<
JS for form_js_complex.js?
Returns array

getName

public string getName( )
  Returns the HTML/JavaScript name of the element.

Returns string $name

isHidden

public bool isHidden( )
  Is this a hidden element?

Returns bool

Private Method Details

setup

private void setup( )
  Kind of a constructor of a derived form element.
The form objects expects one constructor form_element()to setup all form element object. So the constructorof every derived class gets never called. To to setupany object that's derived from form_element the derivedobject has to override this method. It's always calledby form_element.

Returns void

See Also form_element()

checkConfiguration

private boolean checkConfiguration( array $element_data )
  Checks the data used to initialize the element.
You should call this function if you're newto the form stuff or debugging complex forms.If there's a problem the function might "throw"several exceptions. The function will notstop work when it finds an error but continue.That means that you can't "catch" the exceptions.Make sure that exception::$AUTO_HANDLE_ERRORSis set to true so that every error messages will beprinted.

Parameter
array $element_data
Data used in form::add_element()
Returns boolean $ok
Throws form_error

thawout

private void thawout( )
  Alias for unfreeze().

Returns void

getfrozen

private abstract string getfrozen( [ string $value ] )
  Returns thr HTML code of the frozen element.

Parameter
string $value = >>""<<
The value is only used with radio buttons.
If the given value is equal to the value of the
element when it was defined, the radio gets selected.
Returns string $html

HTML code of the frozen element.
See Also get(), show()

show

private abstract void show( [ string $value ] )
  Print version of get().

Parameter
string $value = >>""<<
The value is only used with radio buttons.
If the given value is equal to the value of the
element when it was defined, the radio gets selected.
Returns void

See Also getfrozen(), show()

validateLength

private string validateLength( [ mixed $value ] )
  Validate the length of the input value.

Parameter
mixed $value = >>""<<
Optional value, if not specified $this->value gets used.
Returns string $errormessage

validateRegEx

private string validateRegEx( [ mixed $value ] )
  Compare the element value with the specified RegExp.

Parameter
mixed $value = >>""<<
Optional value, if not specified $this->value gets used.
Returns string $errormessage
See Also validateLength()

doValidation

private boolean doValidation( string $event )
  Validate this event?

Parameter
string $event
Returns boolean $ok
Throws form_error

getJSonActivation

private string getJSonActivation( )
  Return a JavaScript onChange attribute if strong Javascript validation is active

Returns string

getCommonHTMLAttributes

private string getCommonHTMLAttributes( )
  Returns a HTML string with the html attributes shared by all element.

Returns string $html

getFrozenHiddenElement

private string getFrozenHiddenElement( [ mixed $value ] )
  Returns the element as a HTML hidden field.

Parameter
mixed $value = >>""<<
value of the hidden field. If left out $this->value get used.
Returns string

HTML hidden field
See Also get()

getFrozenTable

private string getFrozenTable( [ boolean $border, mixed $value ] )
  Returns the elements as a HTML table.

Parameter
boolean $border = >>false<<
"border = 1" to the table?
mixed $value = >>""<<
value of the hidden field. If left out $this->value get used.
Returns string

HTML table
See Also get()

getJSvalue

private array getJSvalue( )
  JavaScript function used to get the value of the element.
Most elements can use document.forms[..].elements[...].value to get thevalue of an element but some need a more sophisticated function. Theseelements must override this function.The JavaScript function provided by this elements should be names "form_elmenttype",e.g. "form_select". The (JS) function gets called with two arguments:string formname, string elementname. It returns the value of the element, seeform_element_select for an example.The function returns the JavaScript code itself and a name for the codesnippet that allows the form object to avoid sending the code twice.

Returns array

[JavaScript function code, JavaScript function name]

getExtraJS

private array getExtraJS( )
  Returns additional JavaScript required by some complex form elements.
Some elements need extra JavaScript functionality to befull featured. Date for example is able to draw a "now" button. When theuser clicks this button, the date selectors change their values to thecurrent date. An additional JavaScript function "form_date_now" handles the clickon the button.The function returns the JavaScript code itself and a name for the codesnippet that allows the form object to avoid sending the code twice.

Returns array

[JavaScript code, JavaScript code snippet name]

Public Field Details

$flag_config_ok

public boolean $flag_config_ok

>>true<<


See Also checkConfiguration()

Private Field Details

$elname

private string $elname

>>""<<

Alias name of the element.
Every element can have two names. One "name" usedin the generated HTML and one "alias" "elname"."elname" was introduced to access a singleradio element in a group of radio elements.Each element of that group has the same "name" (HTML)an can have a unique (form wide) "alias" elname.

$name

private string $name

>>""<<

HTML name attribute of the element.
Make sure that the name of select multipleelements end with a pair of empty square brackets "[]".

$value

private string $value

>>""<<

Value of the element.

$additional_html

private string $additional_html

>>""<<

Additional HTML attributes.
The string will be added to the generated HTML without any validation.

$frozen

private boolean $frozen

>>false<<

Is the element frozen?

$class

private string $class

>>""<<

HTML/CSS class attribute.

$id

private string $id

>>""<<

HTML/CSS id attribute.

$style

private string $style

>>""<<

HTML/CSS style attribute

$shared_required_fields

private array $shared_required_fields

>>array ( "type" => "string", "name" => "string" )<<

List of required fields every element needs and their type.
Have a look at checkConfiguration() for more informationon debugging form elements.

See Also $required_fields, $shared_optional_fields, checkConfiguration()

$required_fields

private array $required_fields

>>array()<<

List of required fields provided by a derived class.

See Also $shared_required_fields, $optional_fields

$shared_optional_fields

private array $shared_optional_fields

>>array ( "value" => "mixed", "elname" => "string", "additional_html" => "string", "validator" => "string", "js_validator" => "string", "frozen" => "boolean", "class" => "string", "id" => "string", "style" => "string" )<<

List of optional fields and their type.
Have a look at checkConfiguration() for more informationon debugging form elements.

See Also $optional_fields, $shared_required_fields, checkConfiguration()

$optional_fields

private array $optional_fields

>>array()<<

List of optional fields provided by a derived class.

See Also $shared_optional_fields, $required_fields

$method

private string $method

>>""<<

Method (POST|GET) used in the form.

$val_events

private array $val_events

>>array( "length" => true, "valid" => true, "intro" => true )<<

Check for ... errors.

$js_mode

private string $js_mode

>>""<<

JavaScript validation mode.
"weak" => onSubmit or "strong" => onChange/onClick.

$form_name

private string $form_name

>>""<<

Name of the form that contains the element.

$validator

private string $validator

>>""<<

Name of a custom validation function provided by the user.
The function is part of MyForm.

$js_validator

private string $js_validator

>>""<<

Custom JavaScript validator.

Packageindex Classtrees Modulegroups Elementlist Report XML Files
PHPDoc 1.0beta