Webman-framework

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

About | Overview | Documentation

 

Documentation > Modules and APIs > webman_db_item_delete_multirows

webman_db_item_delete_multirows

 

Description:

Multi phases component-type module that provides dynamic control on database table items for multi-rows 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 proposed view template is mainly used as confirmation form page for delete operation by displaying a rows of item's fields and 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_multirows 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_multirows module previously.

The DATAHTML template-element (lines 18-24) named form_db_field is the place where the current rows of 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_$row_idx_ till $db_field_name_n_$row_idx_ treated by Data_HTML_Map module as place-holders to render the coresspond CGI parameters which used to hold the fields' values of database item rows to be deleted. This requires database item rows field names and values to be first injected as a CGI parameters in the form and series of parameter's names as follows:

$db_field_name_1_0, ..., $db_field_name_n_0,
$db_field_name_1_1, ..., $db_field_name_n_1,
...
$db_field_name_1_n, ..., $db_field_name_n_n

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 settings that will be explained in the next main section (section 2, code lines 6-7 or line 9).

Two form's submit buttons (lines 29-30) 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(s)                      
  5 <p />                                                                               
  6 <form method="POST" action="./index.cgi">                                           
  7 <!-- dynamic_content_ name=form_hidden_field //-->                                  
  8 <table border="1">                                                                  
  9   <tr>                                                                              
 10     <td align="right" valign="top"><b>Num. </b></td>                                
 11     <td valign="top">field_caption_1</td>                                           
 12     <td valign="top">field_caption_2</td>                                           
 13     ...                                                                             
 14     <td valign="top">field_caption_n</td                                            
 15   </tr>                                                                             
 16                                                                                     
 17   <!-- start_datahtml_ name=form_db_field //-->                                     
 18   <tr>                                                                              
 19    <td align="right" valign="top"><b>$row_num_. </b></td>                           
 20    <td>$db_field_name_1_$row_idx_</td>                                              
 21    <td>$db_field_name_2_$row_idx_</td>                                              
 22    ...                                                                              
 23    <td>$db_field_name_n_$row_idx_</td>                                              
 24   </tr>                                                                             
 25   <!-- end_datahtml_ //-->                                                          
 26                                                                                     
 27   <tr>                                                                              
 28     <td align="right" colspan="6">                                                  
 29       <input name="button_submit" type="submit" id="button_submit" value="Proceed"/>
 30       <input name="button_submit" type="submit" id="button_submit" value="Cancel"/> 
 31     </td>                                                                           
 32   </tr>                                                                             
 33 </table>                                                                            
 34 </form>                                                                             
 35 <!-- end_view_ //-->                                                                
 36 </body>                                                                             
 37 </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. Since this module support multi-rows item deletion, the coressponds SQL strings constructed will be a series of strings depend on the number of series of items' key field passed as CGI parameters named in the form of key_field_name_0, key_field_name_1, ..., key_field_name_n.

The framework implements CGI parameters database cache through GMM_CGI core module implementations and webman_db_item_delete_multirows 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 parameter's 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 the delete's 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_multirows;                                                                                       
  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 of the customization tasks are reflect to multi phases component-type module featured by webman_db_item_delete_multirows as explained previously (section 3). Customizations inside child modules provide more fine-grained control on each phases involved (lines 46-53). An equivalents tasks from previous example (section 3) for handling succeed delete operation and last phase conditions are now done at lines 57-60 and lines 84-88.

  1 package child_module_name;                                  
  2                                                                               
  3 use webman_db_item_delete_multirows;                                          
  4                                                                               
  5 @ISA=("webman_db_item_delete_multirows");                                     
  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                                                                               
 55     my $status = $this->SUPER::run_Task();                                    
 56                                                                               
 57     if ($status) {                                                            
 58         ### Do other extra tasks after delete operation is succeed.           
 59         ### ...                                                               
 60     }                                                                         
 61 }                                                                             
 62                                                                               
 63 sub end_Task {                                                                
 64     my $this = shift @_;                                                      
 65                                                                               
 66     my $cgi = $this->get_CGI;                                                 
 67     my $dbu = $this->get_DBU;                                                 
 68     my $db_conn = $this->get_DB_Conn;                                         
 69                                                                               
 70     my $login_name = $this->get_User_Login;                                   
 71     my @groups = $this->get_User_Groups;                                      
 72                                                                               
 73     ### Skeleton code to check if current user's groups are match with        
 74     ### specific intended group name.                                         
 75     #my $group_name = "???";                                                  
 76     #my $match_group = $this->match_Group($group_name, @groups);              
 77                                                                               
 78     ### It's mandatory to call this for multi phases modules                  
 79     ### to reset some of the no longer required CGI data.                     
 80     $this->SUPER::end_Task();                                                 
 81                                                                               
 82     ### Put other extra end-task jobs after this line.                        
 83                                                                               
 84     ### Set to other related content.                                         
 85     #$this->set_Content("...");                                               
 86                                                                               
 87     ### Jump to other URL.                                                    
 88     #$cgi->redirect_Page($url);                                               
 89 }                                                                             
 90                                                                               
 91 1;