Webman-framework

Lightweight, Component-based, and Database-oriented Web Application Framework

About | Overview | Documentation

 

Documentation > Modules and APIs > webman_db_item_delete

webman_db_item_delete

 

Description:

Multi phases component-type module that provides dynamic control on database table items delete operation.

 

Dependencies:

Webman-framework's Core Modules:

  • CGI_HTML_Map (Composition)
  • Data_HTML_Map (Composition)
  • DBI_HTML_Map (Composition)

Webman-framework's Component-type Modules:
  • CGI_Component::webman_CGI_component (Inheritance)
  • webman_link_path_generator (Composition)

 

1. View Template

The view template is mainly used as confirmation form page for delete operation by displaying current item fields values involved. If there is no view template assigned to the module the confirmation phase will be skipped.

The DYNAMIC_CONTENT template-element (line 4) named link_path will be processed by webman_link_path_generator module inside process_DYNAMIC hook function. It's used as place-holder to render current application's link path when webman_db_item_delete module is called. The next DYNAMIC_CONTENT template-element (line 7) named form_hidden_field is used as place-holder for HTML-form's hidden input element. This hidden input element is used as an entity to pass the parameter named link_id (via POST-method) which is the standard CGI parameter name used to refer nodes' IDs that construct the overall application's link structure. The logic is to use again node's link-id which is used to call webman_db_item_delete module previously.

The DATAHTML template-element (lines 10-13) named form_db_field is the place where the current database item fields values to be deleted will be rendered. Inside the process_DATAHTML hook function, this template-element will be manipulated by Data_HTML_Map core module. Template-element's word patterns in the form of $db_field_name_1_ till $db_field_name_n_ treated by Data_HTML_Map module as place-holders to render the coresspond CGI parameters which used to hold the item fields values to be deleted. This requires database item field names and values to be first injected as CGI parameters named in the form of aforementioned word patterns. Database item field names and values are retrieved from Table_List_Data instance, created by DBI_HTML_Map core module using SQL string command automatically or manually constructed via module's basic parameter setting that will be explained in the next main section (section 2, code lines 6-7 or line 9).

Two form's submit buttons (lines 19-20) with identical name button_submit but having two different values (Proceed and Cancel) are the default settings to provide users the options to proceed or cancel delete operation when confirmation phase is applied. In other word the module by default will check the input type element named button_submit and look at its value either Proceed or Cancel before decide to continue or cancel the delete operation.

  1 <html>                                                                              
  2 <body>                                                                              
  3 <!-- start_view_ //-->                                                              
  4 <!-- dynamic_content_ name=link_path //--> &gt; Delete Item                         
  5 <p />                                                                               
  6 <form action="index.cgi" method="post">                                             
  7 <!-- dynamic_content_ name=form_hidden_field //-->                                  
  8 <table border="1">                                                                  
  9   <!-- start_datahtml_ name=form_db_field //-->                                     
 10   <tr><td>field_caption_1</td><td>$db_field_name_1_</td></tr>                       
 11   <tr><td>field_caption_2</td><td>$db_field_name_2_</td></tr>                       
 12   ...                                                                               
 13   <tr><td>field_caption_n</td><td>$db_field_name_n_</td></tr>                       
 14   <!-- end_datahtml_ //-->                                                          
 15                                                                                     
 16   <tr>                                                                              
 17     <td>&nbsp;</td>                                                                 
 18     <td>                                                                            
 19       <input name="button_submit" type="submit" id="button_submit" value="Proceed"/>
 20       <input name="button_submit" type="submit" id="button_submit" value="Cancel"/> 
 21     </td>                                                                           
 22   </tr>                                                                             
 23 </table>                                                                            
 24 </form>                                                                             
 25 <!-- end_view_ //-->                                                                
 26 </body>                                                                             
 27 </html>                                                                             


 
2. Instantiation and Basic Parameter Setting

SQL string to delete database item is automatically generated based on arguments passed at lines 6-7. SQL string to display database item fields values to be deleted will also automatically generated based on these arguments unless the optional function at line 9 is used. Key-field values of item to be delete are passed to the module using CGI parameters and mapped to the string arguments using the word pattern in the form of $cgi_key_field_name_. This form of word pattern is actually following CGI_HTML_Map module implementation since the final SQL statements to be executed are constructed with the help of this core module.

The framework implements CGI parameters database cache through GMM_CGI core module implementations and webman_db_item_delete module can automatically remove no longer required CGI parameters from the cache when the delete operation last phase has been reached. Obviously, key-field values for delete operation passed as CGI parameters are among which will be automatically removed from the cache. Other specific CGI parameters can also be forced to be removed by passing the CGI parameters names to the set_Last_Phase_CGI_Data_Reset module's function (line 20).

After delete operation has reach its last phase, it's normal in many web applications, to bring back the users to the previous page that point to current delete page. It can simply be done by telling the module the previous page's URL (line 24) that make a link to current delete page. Other options for doing this task can be done as explained in the next section (section 3, code line 47 or line 50);

  1 my $component = new webman_db_item_delete;                                                                                                 
  2                                                                                                                                            
  3 $component->set_CGI($cgi);                                                                                                                 
  4 $component->set_DBI_Conn($db_conn);                                                                                                        
  5                                                                                                                                            
  6 $component->set_Table_Name("table_name_1_ ... table_name_n_");                                                                             
  7 $component->set_Delete_Keys_Str("key_field_1='\$cgi_key_field_1_'  and ... and key_field_n='\$cgi_key_field_n_'");                         
  8                                                                                                                                            
  9 #$component->set_SQL_View("select * from table_name_ where key_field_1='\$cgi_key_field_1_' and ... and key_field_n='\$cgi_key_field_n_'");
 10                                                                                                                                            
 11 ### Option to debug SQL satement generated by the module.                                                                                  
 12 #$component->set_SQL_Debug(1);                                                                                                             
 13                                                                                                                                            
 14 #$component->set_Submit_Button_Name($submit_button_name_); ### Default is "button submit".                                                 
 15 #$component->set_Proceed_On_Submit($proceed_button_value); ### Default is "Proceed".                                                       
 16 #$component->set_Cancel_On_Submit($cancel_button_value);   ### Default is "Cancel".                                                        
 17                                                                                                                                            
 18 ### Option to remove specific CGI parameters from being cache into database                                                                
 19 ### when the last phase of item delete operation is reached.                                                                               
 20 #$component->set_Last_Phase_CGI_Data_Reset("param_name_1 param_name_2 ... param_name_n");                                                  
 21                                                                                                                                            
 22 ### Option to automatically change the current active page by going                                                                        
 23 ### to other URL when last phase has been reached.                                                                                         
 24 #$component->set_Last_Phase_URL_Redirect($url);                                                                                            
 25                                                                                                                                            
 26 ### Don't assign view template if want to skip the confirmation phase.                                                                     
 27 $component->set_Template_Default($template_file);                                                                                          
 28                                                                                                                                            


 
3. Component-type Generic Function Calls

The proposed implementations below are slightly different from the basic generic function calls of standard component-type modules since webman_db_item_delete is categorized as multi phases component-type module. The main differences are:

  • Component's run_Task function (line 31) will return the status of true or false. It's true if the delete operation is proceed and succeed. Other extra tasks for handling this status condition is now considerable (lines 33-36).
  • There are requirements to accomplish other related tasks if delete operation has reach its last phase (lines 44-51).
When last phase has been reached there are options to change the current active page by directly change the content (line 47) or just redirect the page to other URL (line 50). However, within the context of framework's sub-controller implementation using webman_component_selector module, these last phase tasks options is not really necessary since the module will automatically reset some related CGI parameters when last phase has been reached causing the sub-controller running other correspond module for its next recursive module's function calling.
 29 if ($component->authenticate) {                                 
 30     ### $status == 1 if delete operation is proceed and succeed.
 31     my $status = $component->run_Task;                          
 32                                                                 
 33     if ($status) {                                              
 34         ### Do other extra tasks if delete operation is succeed.
 35         ### ...                                                 
 36     }                                                           
 37                                                                 
 38     $component->process_Content;                                
 39 }                                                               
 40                                                                 
 41 my $content = undef;                                            
 42                                                                 
 43 if ($component->last_Phase) {                                   
 44     $component->end_Task;                                       
 45                                                                 
 46     ### Set to other related content .                          
 47     #$content = "...";                                          
 48                                                                 
 49     ### Jump to other URL.                                      
 50     #$cgi->redirect_Page($url);                                 
 51                                                                 
 52 } else {                                                        
 53     $content = $component->get_Content;                         
 54 }                                                               

The next proposed implementations is the more simple version but requires internal customizations inside child module implementations such as shown in the next section (section 4).
 29 if ($component->authenticate) {       
 30     $component->run_Task;             
 31     $component->process_Content;      
 32 }                                     
 33                                       
 34 if ($component->last_Phase) {         
 35     $component->end_Task;             
 36 }                                     
 37                                       
 38 my $content = $component->get_Content;


 
4. Child Module for Customization

Most generic customization tasks are reflect to multi-phases character featured by the base module as already explained in the previous section (section 3). Customizations inside child modules provide more fine-grained control on each phases involved (lines 46-62). An equivalent tasks from previous example (section 3) for handling succeed delete operation and last phase condition can be done internally inside the child module (lines 66-69 and lines 93-97).

  1 package child_module_name;                                  
  2                                                                               
  3 use webman_db_item_delete;                                                    
  4                                                                               
  5 @ISA=("webman_db_item_delete");                                               
  6                                                                               
  7 sub new {                                                                     
  8     my $class = shift;                                                        
  9                                                                               
 10     my $this = $class->SUPER::new();                                          
 11                                                                               
 12     #$this->set_Debug_Mode(1, 1);                                             
 13                                                                               
 14     bless $this, $class;                                                      
 15                                                                               
 16     return $this;                                                             
 17 }                                                                             
 18                                                                               
 19 sub get_Name {                                                                
 20     my $this = shift @_;                                                      
 21                                                                               
 22     return __PACKAGE__;                                                       
 23 }                                                                             
 24                                                                               
 25 sub get_Name_Full {                                                           
 26     my $this = shift @_;                                                      
 27                                                                               
 28     return $this->SUPER::get_Name_Full . "::" . __PACKAGE__;                  
 29 }                                                                             
 30                                                                               
 31 sub run_Task {                                                                
 32     my $this = shift @_;                                                      
 33                                                                               
 34     my $cgi = $this->get_CGI;                                                 
 35     my $dbu = $this->get_DBU;                                                 
 36     my $db_conn = $this->get_DB_Conn;                                         
 37                                                                               
 38     my $login_name = $this->get_User_Login;                                   
 39     my @groups = $this->get_User_Groups;                                      
 40                                                                               
 41     ### Skeleton code to check if current user's groups are match with        
 42     ### specific intended group name.                                         
 43     #my $group_name = "???";                                                  
 44     #my $match_group = $this->match_Group($group_name, @groups);              
 45                                                                               
 46     if ($this->confirm_Phase) {                                               
 47         ### Confirm phase extra tasks.                                        
 48         #$cgi->add_Debug_Text("confirm_Phase", __FILE__, __LINE__, "TRACING");
 49                                                                               
 50     } elsif($this->last_Phase) {                                              
 51         ### Last phase extra tasks.                                           
 52         #$cgi->add_Debug_Text("last_Phase", __FILE__, __LINE__, "TRACING");   
 53                                                                               
 54         if ($this->check_Button_On_Submit("proceed_")) {                      
 55             ### Proceed delete operation.                                     
 56             ### ???                                                           
 57                                                                               
 58         } else {                                                              
 59             ### Cancel delete operation.                                      
 60             ### ???                                                           
 61         }                                                                     
 62     }                                                                         
 63                                                                               
 64     my $status = $this->SUPER::run_Task();                                    
 65                                                                               
 66     if ($status) {                                                            
 67         ### Do other extra tasks after delete operation is succeed.           
 68         ### ...                                                               
 69     }                                                                         
 70 }                                                                             
 71                                                                               
 72 sub end_Task {                                                                
 73     my $this = shift @_;                                                      
 74                                                                               
 75     my $cgi = $this->get_CGI;                                                 
 76     my $dbu = $this->get_DBU;                                                 
 77     my $db_conn = $this->get_DB_Conn;                                         
 78                                                                               
 79     my $login_name = $this->get_User_Login;                                   
 80     my @groups = $this->get_User_Groups;                                      
 81                                                                               
 82     ### Skeleton code to check if current user's groups are match with        
 83     ### specific intended group name.                                         
 84     #my $group_name = "???";                                                  
 85     #my $match_group = $this->match_Group($group_name, @groups);              
 86                                                                               
 87     ### It's mandatory to call this for multi phases modules                  
 88     ### to reset some of the no longer required CGI data.                     
 89     $this->SUPER::end_Task();                                                 
 90                                                                               
 91     ### Put other extra end-task jobs after this line.                        
 92                                                                               
 93     ### Set to other related content.                                         
 94     #$this->set_Content("...");                                               
 95                                                                               
 96     ### Jump to other URL.                                                    
 97     #$cgi->redirect_Page($url);                                               
 98 }                                                                             
 99                                                                               
100 1;