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

Class: GForm_Ctrl

Source Location: /form/gform_ctrl.class.php

Class GForm_Ctrl

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

Controller for Guarder_Form

Located in /form/gform_ctrl.class.php [line 37] 

Tangra_Class
   |
   --Form_Ctrl
      |
      --GForm_Ctrl
Author(s):
API Tags:
Abstract:  

Properties

Methods
[ Top ]
Descendants
Class Overview | Descendants | Inherited Properties and Methods | Property Summary | Properties Detail | Method Summary | Methods Detail | Constants
Child Class Description
GForm_Ctrl_With_Object Controller for Guarded_Form with I_DB_Storable Object

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

Inherited From Form_Ctrl

Form_Ctrl::$exports
Form_Ctrl::$form
Form_Ctrl::$form_view
Form_Ctrl::$system_name

Inherited From Form_Ctrl

Form_Ctrl::__construct()
Constructor
Form_Ctrl::create_form()
User have to define this method and to return instance of Form
Form_Ctrl::create_form_view()
User have to define this method and to return instance of Form_View
Form_Ctrl::export()
Alias of $this->exports->add_pair()
Form_Ctrl::get_form()
Returns reference to Form object
Form_Ctrl::get_form_submit_event()
Returns form's submit event
Form_Ctrl::get_form_submit_events()
Returns events of form submission both for <input type="submit" and <input type="image"
Form_Ctrl::get_form_view()
Return reference to Form_View object
Form_Ctrl::get_system_name()
Gets name
Form_Ctrl::get_tple_exports()
Gets TPLE_Exports for the form
Form_Ctrl::on_bad_submit()
This method will be called when form submit is not good, i.e. Form_Ctrl::SUBMIT_RESULT_ERROR
Form_Ctrl::on_good_submit()
This method is called when submit is OK.
Form_Ctrl::prepare_for_show()
Descendants of Form_Ctrl may use this method to prepare the form
Form_Ctrl::process_submit()
Processes submit of the form
Form_Ctrl::query_form()
Returns copy of Form object
Form_Ctrl::query_form_view()
Returns copy of Form_View object
Form_Ctrl::set_system_name()
Sets this object's name
Form_Ctrl::_create_form()
Internally called method which sole purpose is to verify that value returned by create_form method is really a instance of Form
Form_Ctrl::_create_form_view()
Internally called method which sole purpose is to verify that value returned by create_form method is really a instance of Form_View

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.

Inherited From Form_Ctrl

Form_Ctrl::SUBMIT_RESULT_ERROR
Form_Ctrl::SUBMIT_RESULT_OK

[ Top ]
Property Summary
Class Overview | Descendants | Inherited Properties and Methods | Property Summary | Properties Detail | Method Summary | Methods Detail | Constants
Form_Guard   $form_guard   Holds Form_Guard object
array   $form_guarded_pairs   Array containing guarded_pairs
mixed   $permanent_external_params  
array   $processed_states   Array of processed states ids
Vars_Manager   $vm   Holds Vars_Manager object

[ Top ]
Method Summary
Class Overview | Descendants | Inherited Properties and Methods | Property Summary | Properties Detail | Constants | Method Summary | Methods Detail
GForm_Ctrl   __construct()   Constructor
void   add_processed_state()   Adds new processed state
void   compose_external_params_var_name()  
void   get_permanent_external_param()  
boolean   get_processed_state()   Returns processed state for submit identified with $form_id
Vars_Manager   get_vm()   Returns reference to used Vars_Mananger
unknown   handle_fresh_submit()   Handles fresh submit of the form.
unknown   handle_repeated_submit()   Handles repeated submit.
void   init_guard_vars()   Initialization of guard pairs array and permanent variable
boolean   is_already_processed()   Checks if this submit is already processed
void   on_accepted_submit()   Called right after submit is accepted.
void   on_process_submit()   Place for your own processing of the validated form data.
void   prepare_for_show()   Prepares form for show
integer   process_submit()   Processes submit
Vars_Mananger   query_vm()   Returns copy of used Vars_Mananger
void   retrieve_permanent_external_params()  
void   set_permanent_external_param()  
void   set_permanent_external_params()  
void   set_vm()   Sets Vars_Manager that will be used

[ Top ]
Properties
Class Overview | Descendants | Inherited Properties and Methods | Property Summary | Properties Detail | Method Summary | Methods Detail | Constants
Form_Guard   $form_guard [line 44]

Holds Form_Guard object

API Tags:
Internal:  
Access:  protected


[ Top ]
array   $form_guarded_pairs [line 68]

Array containing guarded_pairs

API Tags:
Internal:  
Access:  private


[ Top ]
mixed   $permanent_external_params = array() [line 71]
API Tags:
Access:  private


[ Top ]
array   $processed_states [line 60]

Array of processed states ids

API Tags:
Internal:  
Access:  private


[ Top ]
Vars_Manager   $vm [line 52]

Holds Vars_Manager object

API Tags:
Internal:  
Access:  private


[ Top ]
Methods
Class Overview | Descendants | Inherited Properties and Methods | Property Summary | Properties Detail | Constants | Method Summary | Methods Detail
Constructor __construct  [line 81]

  GForm_Ctrl __construct( $system_name, Vars_Manager $vm, stying $

Constructor

Parameters:
stying   $ Name of the controller
Vars_Manager   $vm:  Permanent Vars_Manager that will be used. Session of Thread VM
   $system_name: 

Redefinition of:
Form_Ctrl::__construct()
Constructor
Redefined in descendants as:

[ Top ]
add_processed_state  [line 323]

  void add_processed_state( string $form_id, boolean $state  )

Adds new processed state

Parameters:
string   $form_id: 
boolean   $state: 

API Tags:
Internal:  
Access:  private


[ Top ]
compose_external_params_var_name  [line 376]

  void compose_external_params_var_name( )


API Tags:
Access:  private


[ Top ]
get_permanent_external_param  [line 386]

  void get_permanent_external_param( $param_name, [ $forgiving = false]  )

Parameters:
   $param_name: 
   $forgiving: 

API Tags:
Access:  public


[ Top ]
get_processed_state  [line 335]

  boolean get_processed_state( string $form_id  )

Returns processed state for submit identified with $form_id

Parameters:
string   $form_id: 

API Tags:
Access:  private


[ Top ]
get_vm  [line 195]

  Vars_Manager get_vm( )

Returns reference to used Vars_Mananger


API Tags:
Internal:  
Access:  protected


[ Top ]
handle_fresh_submit  [line 226]

  unknown handle_fresh_submit( unknown_type $form_id  )

Handles fresh submit of the form.

GForm_Ctrl guarantees that only one submit of the form (with same data, for example when visitor to your site clicks multiple times on submit button) will be processed. That means, for example, that you will not get multiple rows in your database with same data, just because visitor was impatient and pumped same form again and again.

 Parameters:
unknown_type   $form_id: 

API Tags:
See:  GForm_Ctrl::handle_repeated_submit()
Internal:  
Access:  private


[ Top ]
handle_repeated_submit  [line 273]

  unknown handle_repeated_submit( unknown_type $form_id  )

Handles repeated submit.

A submit is considered repeated when form_guard detects that same data is submited more than once. In this case "same data" means not just the casual form data but also form_id and guard_value hidden fields. handle_repeated_submit is smart enough to detect state of the last fresh submit (@see GForm_Ctrl::handle_fresh_submit) and to return it.

Usualy repeated submits happens when impatient visitor to your site clicks submit button on a form multile times. Other case is when page that has received submit is refreshed with F5 or "Refresh" button of the browser.

From application point of view repeated submits are just "skipped", i.e. there are no calls of on_process_submit

From visitor's point of view repeated submit is 100% transparent - he/she does not notice any additional activities

 Parameters:
unknown_type   $form_id: 

API Tags:
Internal:  
Access:  private


[ Top ]
init_guard_vars  [line 130]

  void init_guard_vars( )

Initialization of guard pairs array and permanent variable


API Tags:
Internal:  
Access:  protected


[ Top ]
is_already_processed  [line 311]

  boolean is_already_processed( string $form_id  )

Checks if this submit is already processed

Parameters:
string   $form_id: 

API Tags:
Internal:  
Access:  private


[ Top ]
on_accepted_submit  [line 161]

  void on_accepted_submit( )

Called right after submit is accepted.

After a form is submited and basic_check is passed, Form->accept_submit() method is called to transfer values from $_POST to fields' values. Immediately after that $this->on_accepted_submit() is called in order to give the user a chance to manipulate fields values if there is such need (which happens vary rare, only in low level code. If required in high level code that may indicate that there is some design flaw).
API Tags:
Access:  protected

Redefined in descendants as:

[ Top ]
on_process_submit  [line 174]

  void on_process_submit( )

Place for your own processing of the validated form data.

Called after form is passed successfully basic_check and also on_good_submit returned true.

For the sake of example - this method is used in form controllers with object to save the object in the DB. Normally is not used in high level code.
API Tags:
Access:  protected

Redefined in descendants as:

[ Top ]
prepare_for_show  [line 95]

  void prepare_for_show( )

Prepares form for show


API Tags:
Internal:  
Access:  public

Redefinition of:
Form_Ctrl::prepare_for_show()
Descendants of Form_Ctrl may use this method to prepare the form
Redefined in descendants as:

[ Top ]
process_submit  [line 109]

  integer process_submit( Web_Context $context  )

Processes submit

Parameters:
Web_Context   $context: 

API Tags:
Return:  Returned value will be Form_Ctrl::SUBMIT_RESULT_ERROR or Form_Ctrl::SUBMIT_RESULT_OK
Internal:  
Access:  public

Redefinition of:
Form_Ctrl::process_submit()
Processes submit of the form

[ Top ]
query_vm  [line 206]

  Vars_Mananger query_vm( )

Returns copy of used Vars_Mananger


API Tags:
Internal:  
Access:  protected


[ Top ]
retrieve_permanent_external_params  [line 354]

  void retrieve_permanent_external_params( $form_id  )

Parameters:
   $form_id: 

API Tags:
Access:  private


[ Top ]
set_permanent_external_param  [line 381]

  void set_permanent_external_param( $param_name, $param_value  )

Parameters:
   $param_name: 
   $param_value: 

API Tags:
Access:  public


[ Top ]
set_permanent_external_params  [line 340]

  void set_permanent_external_params( $form_id  )

Parameters:
   $form_id: 

API Tags:
Access:  private


[ Top ]
set_vm  [line 184]

  void set_vm( Vars_Manager $vm  )

Sets Vars_Manager that will be used

Parameters:
Vars_Manager   $vm: 

API Tags:
Internal:  
Access:  protected


[ Top ]