Webman-framework

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

About | Overview | Documentation

 

Documentation > Modules and APIs > webman_db_item_insert

webman_db_item_insert

 

Description:

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

 

Dependencies:

Webman-framework's Core Modules:

  • Data_HTML_Map (Composition)
  • HTML_DB_Map (Composition)

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

 

1. View Template

There are two view template files might be assigned to a single webman_db_item_insert module. First is an insert form page for item's field entries and the second is a confirmation page for displaying back fields and their values entered before proceed with the insert operation. If there is no second view template assigned to the module the confirmation phase will be skipped.

1.1 Insert Form Page

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_insert 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_insert module previously.

The DATAHTML template-element (lines 10-27) named form_db_field is passed to process_DATAHTML hook function and manipulated by Data_HTML_Map core module. The input-elements enclosed within the DATAHTML template-element which will be later passed as CGI parameters are named in the form of $db_field_name_1, ..., till $db_field_name_n to adhere the naming convention requirements imposed by other core module (HTML_DB_Map) that is responsible for the real database insert operation. Note that inside the DATAHTML template-element, $db_field_name_1 and $db_field_name_1_ are two different things. The former is an input-element name to be passed as CGI parameter representing item field name and value involved in the insert operation. The later is template-element's word pattern, treated by Data_HTML_Map module as a place-holder to render the coresspond CGI parameter value. Template's word patterns $fe_field_name_1_, ..., $fe_field_name_n_ are used as place-holders for highlighting errors on field values entered.

Two form's submit buttons (lines 33-34) 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 the submission of insert form. 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 insert form submission.

  1 <html>                                                                                           
  2 <body>                                                                                           
  3 <!-- start_view_ //-->                                                                           
  4 <!-- dynamic_content_ name=link_path //--> &gt; Insert Item                                      
  5 <p />                                                                                            
  6 <form method="POST" action="./index.cgi">                                                        
  7 <!-- dynamic_content_ name=form_hidden_field //-->                                               
  8 <table border="1">                                                                               
  9   <!-- start_datahtml_ name=form_db_field //-->                                                  
 10   <tr>                                                                                           
 11     <td>field_caption_1</td>                                                                     
 12     <td>                                                                                         
 13       <input name="$db_field_name_1" type="text" id="$db_field_name_1" value="$db_field_name_1_">
 14       </br>                                                                                      
 15       $fe_field_name_1_                                                                          
 16     </td>                                                                                        
 17   </tr>                                                                                          
 18   ...                                                                                            
 19   ...                                                                                            
 20   <tr>                                                                                           
 21     <td>field_caption_n</td>                                                                     
 22     <td>                                                                                         
 23       <input name="$db_field_name_n" type="text" id="$db_field_name_n" value="$db_field_name_n_">
 24       </br>                                                                                      
 25       $fe_field_name_n_                                                                          
 26     </td>                                                                                        
 27   </tr>                                                                                          
 28   <!-- end_datahtml_ //-->                                                                       
 29                                                                                                  
 30   <tr>                                                                                           
 31     <td>&nbsp;</td>                                                                              
 32     <td>                                                                                         
 33       <input name="button_submit" type="submit" id="button_submit" value="Proceed"/>             
 34       <input name="button_submit" type="submit" id="button_submit" value="Cancel"/>              
 35     </td>                                                                                        
 36   </tr>                                                                                          
 37 </table>                                                                                         
 38 </form>                                                                                          
 39 <!-- end_view_ //-->                                                                             
 40 </body>                                                                                          
 41 </html>                                                                                          

1.2 Confirmation Form Page

View template for confirmation form page also contains two DYNAMIC_CONTENT template-elements (lines 4 and 7) that play the same roles as explained in insert form page above. The DATAHTML template-element (lines 10-14) is also the same but doesn't contain any form's input-elements and word patterns for highlighting field entries errors. At the time confirmation form page processed by the module, all CGI parameters passed from the previous insert form page are already cached into the database. DATAHTML template-element is solely used to display back item's field values held by these cached CGI parameters for confirmation purpose.

Three form's submit buttons (lines 20-22) with identical name button_submit but having three different values (Confirm, Edit, and Cancel) are the default settings to provide users the options to confirm or cancel the insert operation, or back to insert form page to edit the field entries. In other word the module by default will check the input-element named button_submit and look at its value either Confirm, Edit, or Cancel before decide to continue or cancel the insert operation, or going back to insert form page to edit the previous data entries.

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


 
2. Instantiation and Basic Parameter Setting

Among crucial parameters setting are field value entries validation. Through the settings (lines 8-10), the module will able to detect errors for blank field entries, field values duplication in current table, and field values existence in current table or other related tables. The string argument passed for blank field entries setting (line 8) are CGI parameters which used to represent item field names and values involved in the insert operation. They are all separated by single spaces in single string argument. Duplicate field values errors detection (line 9) might based on combination of current table fields (field_name_2&field_name_3). String argument for field values existence (line 10) are one-to-one mappings of field name and its table (field_name=>table_name). As an example, field values existence error might happen if try to register student's course with course-code still not exist from inside the course table.

To exclude particular fields from being involved in the insert operations, though they are already represented as CGI parameters as explained in section 1, setting via set_Exceptional_DB_Fields module's function (line 12) can be used.

The framework implements CGI parameters database cache through GMM_CGI core module implementations and webman_db_item_insert module can automatically remove no longer required CGI parameters from the cache when the insert operation last phase has been reached. Obviously, CGI parameters which used to represent field names and values involved in the insert operation 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 names to the set_Last_Phase_CGI_Data_Reset module's function (line 23).

By default, cancel and confirm button values are used as indicators by the module to end the phase of insert operation. To enforce single button indication for insert last phase operation, function call (line 25) can be used. Normally confirm button value is the one should be passed as an argument to this function call thus change cancel button value role as an indicator to reset item field entries.

  1 my $component = new webman_db_item_insert;                                                               
  2                                                                                                          
  3 $component->set_CGI($cgi);                                                                               
  4 $component->set_DBI_Conn($db_conn);                                                                      
  5                                                                                                          
  6 $component->set_Table_Name($table_name);                                                                 
  7                                                                                                          
  8 $component->set_Check_On_CGI_Data("\$db_field_name_1 ... \$db_field_name_n");                            
  9 $component->set_Check_On_Fields_Duplication("field_name_1 field_name_2&field_name_3 ... field_name_n");  
 10 $component->set_Check_On_Fields_Existence("field_name_1=>table_name_1, ..., field_name_n=>table_name_n");
 11                                                                                                          
 12 #$component->set_Exceptional_DB_Fields("field_name_1 ... field_name_n");                                 
 13                                                                                                          
 14 ### Option to debug SQL satement generated by the module.                                                
 15 #$component->set_SQL_Debug(1);                                                                           
 16                                                                                                          
 17 #$component->set_Submit_Button_Name($submit_button_name);  ### default is "button_submit"                
 18 #$component->set_Proceed_On_Submit($proceed_button_value); ### default is "Proceed"                      
 19 #$component->set_Confirm_On_Submit($confirm_button_value); ### default is "Confirm"                      
 20 #$component->set_Edit_On_Submit($edit_button_value);       ### default is "Edit"                         
 21 #$component->set_Cancel_On_Submit($cancel_button_value);   ### default is "Cancel"                       
 22                                                                                                          
 23 #$component->set_Last_Phase_CGI_Data_Reset("param_name_1 param_name_2 ... param_name_n");                
 24                                                                                                          
 25 #$component->set_Last_Phase_Only_If_Submit_Is($submit_button_value);                                     
 26                                                                                                          
 27 ### Insert form page template.                                                                           
 28 $component->set_Template_Default($template_file);                                                        
 29                                                                                                          
 30 ### Don't assign confirm view template if want to skip the confirmation phase.                           
 31 $component->set_Template_Default_Confirm($template_file_confirm);                                        
 32                                                                                                          


 
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_insert is categorized as multi phases component-type module. The main differences are:

  • Component's run_Task function (line 35) will return the status of true or false. It's true if the insert operation is proceed and succeed. Other extra tasks for handling this status condition is now considerable (lines 37-40).
  • There are requirements to do other related tasks if insert operation has reach its last phase (lines 48-55).
When last phase has been reached there are options to change the current active page by directly change the content (line 51) or just redirect the page to other URL (line 54). 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 call.
 33 if ($component->authenticate) {                                 
 34     ### $status == 1 if insert operation is proceed and succeed.
 35     my $status = $component->run_Task;                          
 36                                                                 
 37     if ($status) {                                              
 38         ### Do other extra tasks if insert operation is succeed.
 39         ### ...                                                 
 40     }                                                           
 41                                                                 
 42     $component->process_Content;                                
 43 }                                                               
 44                                                                 
 45 my $content = undef;                                            
 46                                                                 
 47 if ($component->last_Phase) {                                   
 48     $component->end_Task;                                       
 49                                                                 
 50     ### Set to other related content .                          
 51     #$content = "...";                                          
 52                                                                 
 53     ### Jump to other URL.                                      
 54     #$cgi->redirect_Page($url);                                 
 55                                                                 
 56 } else {                                                        
 57     $content = $component->get_Content;                         
 58 }                                                               

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).
 33 if ($component->authenticate) {       
 34     $component->run_Task;             
 35     $component->process_Content;      
 36 }                                     
 37                                       
 38 if ($component->last_Phase) {         
 39     $component->end_Task;             
 40 }                                     
 41                                       
 42 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 43-58). An equivalent tasks from previous example (section 3) for handling succeed insert operation and last phase condition can be done internally inside the child module (lines 62-64 and lines 88-92). There is also customize_CGI_Data function to be overriden (lines 105-111) to manipulate the CGI parameters prior the execution of insert operation.

  1 package child_module_name;                                                                                     
  2                                                                                                                                  
  3 use webman_db_item_insert;                                                                                                       
  4                                                                                                                                  
  5 @ISA=("webman_db_item_insert");                                                                                                  
  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     my $match_group = $this->match_Group($group_name_, @groups);                                                                 
 42                                                                                                                                  
 43     if ($this->init_Phase) {                                                                                                     
 44         ### init. phase extra tasks                                                                                              
 45         #$cgi->add_Debug_Text("init_Phase", __FILE__, __LINE__, "TRACING");                                                      
 46                                                                                                                                  
 47     } elsif ($this->confirm_Phase) {                                                                                             
 48         ### confirm phase extra tasks                                                                                            
 49         #$cgi->add_Debug_Text("confirm_Phase", __FILE__, __LINE__, "TRACING");                                                   
 50                                                                                                                                  
 51     } elsif ($this->edit_Phase) {                                                                                                
 52         ### edit phase extra tasks                                                                                               
 53         #$cgi->add_Debug_Text("edit_Phase", __FILE__, __LINE__, "TRACING");                                                      
 54                                                                                                                                  
 55     } elsif($this->last_Phase) {                                                                                                 
 56         ### last phase extra tasks                                                                                               
 57         #$cgi->add_Debug_Text("last_Phase", __FILE__, __LINE__, "TRACING");                                                      
 58     }                                                                                                                            
 59                                                                                                                                  
 60     my $status = $this->SUPER::run_Task();                                                                                       
 61                                                                                                                                  
 62     if ($status) {                                                                                                               
 63         ### Extra tasks if insert operation is succeed.                                                                          
 64     }                                                                                                                            
 65 }                                                                                                                                
 66                                                                                                                                  
 67 sub end_Task {                                                                                                                   
 68     my $this = shift @_;                                                                                                         
 69                                                                                                                                  
 70     my $cgi = $this->get_CGI;                                                                                                    
 71     my $dbu = $this->get_DBU;                                                                                                    
 72     my $db_conn = $this->get_DB_Conn;                                                                                            
 73                                                                                                                                  
 74     my $login_name = $this->get_User_Login;                                                                                      
 75     my @groups = $this->get_User_Groups;                                                                                         
 76                                                                                                                                  
 77     ### Skeleton code to check if current user's groups are match with                                                           
 78     ### specific intended group name.                                                                                            
 79     #my $group_name = "???";                                                                                                     
 80     #my $match_group = $this->match_Group($group_name, @groups);                                                                 
 81                                                                                                                                  
 82     ### It's mandatory to call this for multi phases modules                                                                     
 83     ### to reset some of the no longer required CGI data.                                                                        
 84     $this->SUPER::end_Task();                                                                                                    
 85                                                                                                                                  
 86     ### Put other extra end-task jobs after this line.                                                                           
 87                                                                                                                                  
 88     ### Set to other related content.                                                                                            
 89     #$this->set_Content("...");                                                                                                  
 90                                                                                                                                  
 91     ### Jump to other URL.                                                                                                       
 92     #$cgi->redirect_Page($url);                                                                                                  
 93 }                                                                                                                                
 94                                                                                                                                  
 95 ### This function will be called just before the insert                                                                          
 96 ### operation is implemented inside the run_Task function.                                                                       
 97 sub customize_CGI_Data { ### 11/10/2011                                                                                          
 98     my $this = shift @_;                                                                                                         
 99     my $te = shift @_;                                                                                                           
100                                                                                                                                  
101     my $cgi = $this->get_CGI;                                                                                                    
102     my $dbu = $this->get_DBU;                                                                                                    
103     my $db_conn = $this->get_DB_Conn;                                                                                            
104                                                                                                                                  
105     ### Example on how to add/insert other linked table primary keys                                                             
106     ### (linked_table_PK) that act as a foreign keys inside current table                                                        
107     ### by refering to one of current table field that act as a unique keys                                                      
108     ### inside the linked table (linked_table_UK)                                                                                
109     #$dbu->set_Table("linked_table_name");                                                                                       
110     #my $linked_table_PK = $dbu->get_Item("linked_table_PK", "linked_table_UK", $cgi->param("\$db_linked_table_UK"));            
111     #$cgi->push_Param("\$db_linked_table_PK", $linked_table_PK);                                                                 
112 }                                                                                                                                
113                                                                                                                                  
114 1;