tangra logo
   
[ class tree: tangra_lib ] [ index: tangra_lib ] [ all elements ]
 

Class: Form

Source Location: /form/form.class.php

Class Form

Class Overview
Class Overview | Descendants | Inherited Properties, Constants, and Methods | Property Summary | Properties Detail | Method Summary | Methods Detail | Constants Summary | Constants Detail

Class Form is used to handle most of the aspects when working with HTML forms

Located in /form/form.class.php [line 52] 

Tangra_Class
   |
   --Form

Properties

Methods
[ Top ]
Descendants
Class Overview | Descendants | Inherited Properties and Methods | Property Summary | Properties Detail | Method Summary | Methods Detail | Constants Summary | Constants Detail
Child Class Description
Guardable_Form Guardable_Form is just Form with hidden fields for form_id and guard_value

[ Top ]
Inherited Properties, Constants, and Methods
Class Overview | Descendants | Inherited Properties, Constants, and Methods | Property Summary | Properties Detail | Method Summary | Methods Detail | Constants Summary | Constants Detail
Inherited Properties Inherited Methods Inherited Constants

Inherited From Tangra_Class

Tangra_Class::get_class_name()
Alias of get_class(). Exist because of historical reasons.
Tangra_Class::__set()
Overides PHP built-in method and just throws exception if called. Purpose - to "forbid" autosetting of nonexisting class properties.

[ Top ]
Constant Summary
Class Overview | Descendants | Inherited Properties, Constants, and Methods | Constants Summary | Constants Detail | Property Summary | Properties Detail | Method Summary | Methods Detail
ENCODING_APPLICATION   Enter description here...
ENCODING_MULTIPART  

[ Top ]
Property Summary
Class Overview | Descendants | Inherited Properties and Methods | Property Summary | Properties Detail | Method Summary | Methods Detail | Constants Summary | Constants Detail
string   $action   Action - page for action attribute
unknown_type   $enctype   Encoding Form::ENCODING_APPLICATION / Form::ENCODING_MULTIPART
array   $fields   Fields of the form
boolean   $form_ok   Status of the submission of the form
integer   $method   Method of sending the form Tangra_Form_Submit_Method::POST/Tangra_Form_Submit_Method::GET
string   $name   Name of the form

[ Top ]
Method Summary
Class Overview | Descendants | Inherited Properties and Methods | Property Summary | Properties Detail | Constants Summary | Constants Detail | Method Summary | Methods Detail
void   accept_submit()   Cycles all fields and calls their accept_submit method
void   add_field()   Adds field to the form
boolean   basic_check()   Performs value check on all fields
void   capture_submit()   Transfers values from $_POST or $_GET into html_value ofd each field
Web_Event_Simple   create_submit_event()   Creates submit event with capture specified by $submit_name
Form   __construct()   Constructor
string   get_action()   Gets action property of the form
unknown   get_enctype()   Gets encoding type
Form_Field   &get_field()   Returns field specified by $field_name
array   &get_fields()   Returns array containing all fields.
unknown   get_field_html_value()   Gets field HTML value
mixed   get_field_value()   Gets Field value
integer   get_method()   Gets method of form submission.
string   get_name()   Gets form name
Web_Event_Simple   get_submit_event()   Returns event of form submission
arrray   get_submit_events()   Returns events of form submission both for <input type="submit" and <input type="image"
string   get_submit_name()   Returns name of the submit button
string   get_submit_x_name()   Returns name of the submit button with "_x" suffix
string   get_submit_y_name()   Returns name of the submit button with "_y" suffix
unknown   is_form_ok()   Returns status of the form
boolean   is_receiving_submit()   Checks if form is receiving submit, i.e. submit_name is present in $_POST or $_GET
void   set_enctype()   Sets encoding type.
void   set_field_error()   Sets field error.
void   set_field_value()   Sets value of form fiels
void   set_method()   Sets the method of submission
void   set_name()   Sets the name of the form
void   translate_values_html2app()   Translates HTML values of the fields to "application" values.

[ Top ]
Properties
Class Overview | Descendants | Inherited Properties and Methods | Property Summary | Properties Detail | Method Summary | Methods Detail | Constants Summary | Constants Detail
string   $action [line 92]

Action - page for action attribute

API Tags:
Internal:  
Access:  private


[ Top ]
unknown_type   $enctype [line 84]

Encoding Form::ENCODING_APPLICATION / Form::ENCODING_MULTIPART

API Tags:
Internal:  
Access:  private


[ Top ]
array   $fields [line 100]

Fields of the form

API Tags:
Internal:  
Access:  protected


[ Top ]
boolean   $form_ok [line 108]

Status of the submission of the form

API Tags:
Internal:  
Access:  private


[ Top ]
integer   $method [line 76]

Method of sending the form Tangra_Form_Submit_Method::POST/Tangra_Form_Submit_Method::GET

API Tags:
Internal:  
Access:  private


[ Top ]
string   $name [line 68]

Name of the form

API Tags:
Internal:  
Access:  private


[ Top ]
Methods
Class Overview | Descendants | Inherited Properties and Methods | Property Summary | Properties Detail | Constants Summary | Constants Detail | Method Summary | Methods Detail
accept_submit  [line 390]

  void accept_submit( )

Cycles all fields and calls their accept_submit method


API Tags:
Internal:  
Access:  public


[ Top ]
add_field  [line 178]

  void add_field( Form_Field $field  )

Adds field to the form

Please note that if the field is Form_Field_File type, encoding of the form will be automatically changed to Form::ENCODING_MULTIPART (that way form will be submited correctly)

 Parameters:
Form_Field   $field: 

API Tags:
Access:  public

Information Tags:
Throws:  TE_Form_Field_Already_Exists

[ Top ]
basic_check  [line 295]

  boolean basic_check( )

Performs value check on all fields

Cycles all fields and call theirs basic_check method
API Tags:
Internal:  
Access:  public


[ Top ]
capture_submit  [line 368]

  void capture_submit( Context $context  )

Transfers values from $_POST or $_GET into html_value ofd each field

Parameters:
Context   $context: 

API Tags:
Internal:  
Access:  public


[ Top ]
create_submit_event  [line 481]

  Web_Event_Simple create_submit_event( string $submit_name  )

Creates submit event with capture specified by $submit_name

Parameters:
string   $submit_name: 

API Tags:
Access:  private


[ Top ]
Constructor __construct  [line 119]

  Form __construct( string $name, string $action, [integer $method = Tangra_Form_Submit_Method::POST], [integer $enctype = Form::ENCODING_APPLICATION]  )

Constructor

Parameters:
string   $name:  Name of the form
string   $action:  Action page
integer   $method:  Tangra_Form_Submit_Method::POST or Tangra_Form_Submit_Method::GET
integer   $enctype:  Form::ENCODING_APPLICATION or Form::ENCODING_MULTIPART

Redefined in descendants as:

[ Top ]
get_action  [line 165]

  string get_action( )

Gets action property of the form


API Tags:
Access:  public


[ Top ]
get_enctype  [line 155]

  unknown get_enctype( )

Gets encoding type


API Tags:
Access:  public


[ Top ]
get_field  [line 264]

  Form_Field &get_field( string $field_name  )

Returns field specified by $field_name

Parameters:
string   $field_name:  name of the field

API Tags:
Access:  public

Information Tags:
Throws:  TE_Form_Field_Not_Exists

[ Top ]
get_fields  [line 252]

  array &get_fields( )

Returns array containing all fields.


API Tags:
Internal:  
Access:  public


[ Top ]
get_field_html_value  [line 235]

  unknown get_field_html_value( unknown_type $field_name  )

Gets field HTML value

HTML value is value of the field as sent by HTTP POST/GET. It is not intended to be called directly by the user except in vary rare and specific circumstances.

 Parameters:
unknown_type   $field_name: 

API Tags:
Internal:  
Access:  public

Information Tags:
Throws:  TE_Form_Field_Not_Exists

[ Top ]
get_field_value  [line 213]

  mixed get_field_value( string $field_name  )

Gets Field value

Parameters:
string   $field_name:  Name of the field

API Tags:
Access:  public

Information Tags:
Throws:  TE_Form_Field_Not_Exists

[ Top ]
get_method  [line 145]

  integer get_method( )

Gets method of form submission.

Returned value will Tangra_Form_Submit_Method::POST or Tangra_Form_Submit_Method::GET
API Tags:
Access:  public


[ Top ]
get_name  [line 133]

  string get_name( )

Gets form name


API Tags:
Access:  public


[ Top ]
get_submit_event  [line 455]

  Web_Event_Simple get_submit_event( )

Returns event of form submission


API Tags:
Access:  public


[ Top ]
get_submit_events  [line 467]

  arrray get_submit_events( )

Returns events of form submission both for <input type="submit" and <input type="image"


API Tags:
Return:  Simple array of Web_Event_Simple elements
Access:  public


[ Top ]
get_submit_name  [line 332]

  string get_submit_name( )

Returns name of the submit button

Name of the submit button contains form name and "_submit" suffix
API Tags:
Internal:  
Access:  public


[ Top ]
get_submit_x_name  [line 345]

  string get_submit_x_name( )

Returns name of the submit button with "_x" suffix

When submit button is image, browsers return submit name plus _x and _y suffixes (position of the click in the image)
API Tags:
Internal:  
Access:  public


[ Top ]
get_submit_y_name  [line 357]

  string get_submit_y_name( )

Returns name of the submit button with "_y" suffix

When submit button is image, browsers return submit name plus _x and _y suffixes (position of the click in the image)
API Tags:
Internal:  
Access:  public


[ Top ]
is_form_ok  [line 319]

  unknown is_form_ok( )

Returns status of the form

Status of the form is the state of the last submission. If all fields are OK then status is true, otherwise - false
API Tags:
Access:  public


[ Top ]
is_receiving_submit  [line 404]

  boolean is_receiving_submit( Context $context  )

Checks if form is receiving submit, i.e. submit_name is present in $_POST or $_GET

Parameters:
Context   $context: 

API Tags:
Internal:  
Access:  public


[ Top ]
set_enctype  [line 547]

  void set_enctype( integer $enctype  )

Sets encoding type.

Must be either Form::ENCODING_APPLICATION or Form::ENCODING_MULTIPART

 Parameters:
integer   $enctype: 

API Tags:
Internal:  
Access:  protected

Information Tags:
Throws:  Tangra_Exception

[ Top ]
set_field_error  [line 441]

  void set_field_error( string $field_name, string $potential_error_name  )

Sets field error.

Each form field may have potential errors. Most of them are built-in, for example - 'mandatory_missing" which means that field is mandatory, but POST/GET does not contain value for it. Each field may have custom errors that are not set during basic_check. In this case, if error condition is true, application have to call set_field_error to tell the field that it is in error.

 Parameters:
string   $field_name:  Name of the field
string   $potential_error_name:  Name of the error

API Tags:
See:  Form_Field
Access:  public


[ Top ]
set_field_value  [line 197]

  void set_field_value( string $field_name, mixed $value  )

Sets value of form fiels

Parameters:
string   $field_name:  Name of the field
mixed   $value:  Value of the field

API Tags:
Access:  public

Information Tags:
Throws:  TE_Form_Field_Not_Exists

[ Top ]
set_method  [line 524]

  void set_method( integer $method  )

Sets the method of submission

Must be either Tangra_Form_Submit_Method::POST or Tangra_Form_Submit_Method::GET

 Parameters:
integer   $method: 

API Tags:
Internal:  
Access:  protected

Information Tags:
Throws:  Tangra_Exception

[ Top ]
set_name  [line 506]

  void set_name( string $name  )

Sets the name of the form

Name of the form must be alphanumeric (underscore is allowed), starting with letter, 50 characters max. Please note that $name will be converted to lowercase.

 Parameters:
string   $name: 

API Tags:
Internal:  
Access:  protected

Information Tags:
Throws:  Tangra_Exception

[ Top ]
translate_values_html2app  [line 280]

  void translate_values_html2app( )

Translates HTML values of the fields to "application" values.


API Tags:
Internal:  
Access:  public


[ Top ]
Constants
Class Overview | Descendants | Constants Summary | Constants Detail | Inherited Properties, Constants, and Methods | Method Summary | Methods Detail
ENCODING_APPLICATION = 'application/x-www-form-urlencoded' [line 57]

Enter description here...


[ Top ]
ENCODING_MULTIPART = 'multipart/form-data' [line 58]

[ Top ]