Webman-framework

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

About | Overview | Documentation

 

Documentation > Modules and APIs > webman_db_item_search

webman_db_item_search

 

Description:

Component-type module that provides dynamic control on database table items for basic search operation. It might be integrated with other component-types module for database item update/delete operations.

 

Dependencies:

Webman-framework's Core Modules:

  • CGI_HTML_Map (Composition)

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

 

1. View Template

Generally there are two types of view template files must be assigned to a single webman_db_item_search module. First is a form page for search's key-field entries and the second is a result page for displaying the found search item(s).

1.1 Key-field Entries Form Page

There are three DYNAMIC_CONTENT template-elements used. All will be passed to and processed inside module's process_DYNAMIC hook function. The first (line 4) named link_path will be manipulated by webman_link_path_generator core module and becomes the place-holder to render current application's link path when webman_db_item_search module is called. The next (line 8) 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_search module previously. The last (line 33) is used as place-holder for search result content generated by either webman_db_item_view or webman_db_item_view_dynamic modules.

HTML-form input-elements for search key-field entries are enclosed inside the CGIHTML template-element (lines 11-24). Input-element names are just simply a direct mappings of field names (key_field_1, ..., key_field_n) from the involved database table. Inside the CGIHTML template-element, CGI parameters which are the previous entered key-field values are mapped back as input-element values using the word patterns $cgi_key_field_1_, ..., $cgi_key_field_n_.

  1 <html>                                                                                   
  2 <body>                                                                                   
  3 <!-- start_view_ //-->                                                                   
  4 <!-- dynamic_content_ name=link_path //-->                                               
  5 <p />                                                                                    
  6                                                                                          
  7 <form method="POST" action="./index.cgi">                                                
  8 <!-- dynamic_content_ name=form_hidden_field //-->                                       
  9 <table>                                                                                  
 10 <!-- start_cgihtml_ //-->                                                                
 11 <tr>                                                                                     
 12   <td>key_field_1_caption</td>                                                           
 13   <td>                                                                                   
 14     <input name="key_field_1" type="text" id="key_field_1" value="$cgi_key_field_1_">    
 15   </td>                                                                                  
 16 </tr>                                                                                    
 17 ...                                                                                      
 18 ...                                                                                      
 19 <tr>                                                                                     
 20   <td>key_field_n_caption</td>                                                           
 21   <td>                                                                                   
 22     <input name="key_field_n" type="text" id="key_field_n" value="$cgi_key_field_n_">    
 23   </td>                                                                                  
 24 </tr>                                                                                    
 25 <!-- end_cgihtml_ //-->                                                                  
 26 <tr>                                                                                     
 27   <td>&nbsp;</td>                                                                        
 28   <td><input name="button_submit" type="submit" id="button_submit" value="Search" /></td>
 29 </tr>                                                                                    
 30 </table>                                                                                 
 31 </form>                                                                                  
 32                                                                                          
 33 <!-- dynamic_content_ name=search_result //-->                                           
 34                                                                                          
 35 <!-- end_view_ //-->                                                                     
 36 </body>                                                                                  
 37 </html>                                                                                  

1.2 Search Result Pages

Since the result might be a single or multiple rows of items, so for the result pages to be used. There are two types of result pages assigned to the module at once. One is for single-row result processed by webman_db_item_view module and the other one is for multi-rows result processed by webman_db_item_view_dynamic module.

1.2.1 Single-row Result Page

  1 <html>                                                       
  2 <body>                                                       
  3 <!-- start_view_ //-->                                       
  4 <table border="1">                                           
  5   <!-- start_dbhtml_ //-->                                   
  6   <tr><th>field_caption_1</th><td>$db_field_name_1_</td></tr>
  7   ...                                                        
  8   <tr><th>field_caption_n</th><td>$db_field_name_n_</td></tr>
  9   <!-- end_dbhtml_ //-->                                     
 10 </table>                                                     
 11 <!-- end_view_ //-->                                         
 12 </body>                                                      
 13 </html>                                                      

1.2.2 Multi-rows Result Page
  1 <html>                                                                      
  2 <body>                                                                      
  3 <!-- start_view_ //-->                                                      
  4                                                                             
  5 <!-- dynamic_content_ name=db_items_num_begin //--> -                       
  6 <!-- dynamic_content_ name=db_items_num_end //--> of                        
  7 <!-- dynamic_content_ name=db_items_num_total //--> Records.                
  8                                                                             
  9 <table border="1">                                                          
 10   <tr>                                                                      
 11     <th>Num.</th>                                                           
 12     <th>field_caption_1</th>                                                
 13     ...                                                                     
 14     <th>field_caption_n</th>                                                
 15   </tr>                                                                     
 16                                                                             
 17   <!-- start_list_ name=main //-->                                          
 18   <tr>                                                                      
 19     <td align="right">$tld_num_.</td>                                       
 20     <td>$tld_field_name_1_</td>                                             
 21     ...                                                                     
 22     <td>$tld_field_name_n_</td>                                             
 23   </tr>                                                                     
 24   <!-- end_list_ //-->                                                      
 25 </table>                                                                    
 26                                                                             
 27 <p />                                                                       
 28                                                                             
 29 <form name="tld_view_dynamic" method="post" action="index.cgi">             
 30   <!-- dynamic_content_ name=form_hidden_field //-->                        
 31                                                                             
 32   Items/List: <input name="inl" type="text" id="inl" value="$inl_" size="3">
 33   &nbsp;                                                                    
 34                                                                             
 35   <!-- start_menu_ name=list //-->                                          
 36     dynamic_menu_items_                                                     
 37   <!-- end_menu_ //-->                                                      
 38   &nbsp;                                                                    
 39                                                                             
 40   List Set Num. :                                                           
 41   <select name="lsn" onChange="document.tld_view_dynamic.submit()">         
 42     <!-- select_ name=lsn //-->                                             
 43   </select>                                                                 
 44 </form>                                                                     
 45 <!-- end_view_ //-->                                                        
 46 </body>                                                                     
 47 </html>                                                                     


 
2. Instantiation and Basic Parameter Setting

SQL command string for database items search operation is automatically generated based on arguments passed at lines 6-7. For more complex search's SQL command, it can be optionally done as shown at line 10. Search's key-field value entries passed as CGI parameters are mapped inside the SQL string arguments in the form of $cgi_key_field_name_. For other parameter settings read the comments provided for each function calls below.

  1 my $component = new webman_db_item_search;                                                        
  2                                                                                                   
  3 $component->set_CGI($cgi);                                                                        
  4 $component->set_DBI_Conn($db_conn);                                                               
  5                                                                                                   
  6 $component->set_Table_Name($table_name);                                                          
  7 $component->set_Key_Field_Search("key_field_1 ... key_field_n");                                  
  8                                                                                                   
  9 ### Option to manually set the SQL command for more complex search operation.                     
 10 #$component->set_SQL("select * from $table_name where key_field_name='$cgi_key_field_name_' ...");
 11                                                                                                   
 12 ### Table's primary key to be injected as CGI parameter and to be used                            
 13 ### as a key-field when search operation is integrated with update/delete                         
 14 ### operations.                                                                                   
 15 $component->set_Key_Field_Primary($key_field_primary);                                            
 16                                                                                                   
 17 ### Options to debug the sql statement used for                                                   
 18 ### search operation as a CGI debug text. Default is                                              
 19 ### set to 0.                                                                                     
 20 #$component->set_SQL_Debug(1);                                                                    
 21                                                                                                   
 22 ### Option to customize the not found item message. Default is:                                   
 23 ### "<font color=\"#FF0000\">No item found for current search entry.</font>"                      
 24 #$component->set_Not_Found_Message("...");                                                        
 25                                                                                                   
 26                                                                                                   
 27 ### Redirect to other page when item is found. Normally it would be applied                       
 28 ### when single item was found and search operation is also integrated with                       
 29 ### update/delete operations. The implementation is done by customizing                           
 30 ### the redirect_Page module's function via function overriding.                                  
 31 #$component->set_Item_Found_URL_Redirect("./index.cgi?link_id=$cgi_link_id_&task=...");           
 32                                                                                                   
 33 ### The three view templates for search's key-field entries, single-row result                    
 34 ### page, and multi-rows result page.                                                             
 35 $component->set_Template_Default($template_field_form);                                           
 36 $component->set_Template_Default_Found($template_found);                                          
 37 $component->set_Template_Default_Found_List($template_found_list);                                


 
3. Component-type Generic Function Calls

if ($component->authenticate) {
    $component->run_Task;
    $component->process_Content;
    $component->end_Task;
}

my $content = $component->get_Content;



 
4. Child Module for Customization

Most basic customization (lines 45-48) is to deal with the situation where search operation return result no matter either single-row or multi-rows items.

If the manual setting (section 2, line 10) is inadequate to generate the required complex search's SQL string command, it can be done programmatically inside the customize_SQL hook function (line 63).

Most common customzation tasks inside redirect_Page hook function is to distinct the situations of single found item, and no item was found or multi-rows returned items. If single item was found and page redirection is set using set_Item_Found_URL_Redirect function (section 2, line 31) the module can be set to just continue it (line 77-79). For the case of multi-rows returned items, integration with update/delete operations, and page redirection has been set, the module could be set to not continue the page redirection (lines 81-85). This will allow the module to first list the returned item rows and let the users choose the exact single item they want to update/delete.

  1 package child_module_name;                                         
  2                                                                                      
  3 use webman_db_item_search;                                                           
  4                                                                                      
  5 @ISA=("webman_db_item_search");                                                      
  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     my $status = $this->SUPER::run_Task;                                             
 44                                                                                      
 45     if ($this->{found}) {                                                            
 46         ### extra tasks when search item was found                                   
 47         ### ???                                                                      
 48     }                                                                                
 49                                                                                      
 50     return $status;                                                                  
 51 }                                                                                    
 52                                                                                      
 53 sub customize_SQL {                                                                  
 54     my $this = shift @_;                                                             
 55                                                                                      
 56     my $cgi = $this->get_CGI;                                                        
 57     my $dbu = $this->get_DBU;                                                        
 58     my $db_conn = $this->get_DB_Conn;                                                
 59                                                                                      
 60     my $sql = $this->{sql};                                                          
 61                                                                                      
 62     ### Next is to customize the $sql string.                                        
 63     $sql = ...;                                                                      
 64                                                                                      
 65     return $sql;                                                                     
 66 }                                                                                    
 67                                                                                      
 68 sub redirect_Page {                                                                  
 69     my $this = shift @_;                                                             
 70     my $te = shift @_;                                                               
 71                                                                                      
 72     my $cgi = $this->get_CGI;                                                        
 73     my $db_conn = $this->get_DB_Conn;                                                
 74     my $db_interface = $this->get_DB_Interface;                                      
 75                                                                                      
 76     if ($cgi->param("button_submit") eq "Search" && $this->{total_item_found} == 1) {
 77         ### Continue to run other module via page redirect.                          
 78         $this->SUPER::redirect_Page;                                                 
 79                                                                                      
 80     } else {                                                                         
 81         ### Search item was not found or search operation return multi-rows          
 82         ### result. Do nothing!!!                                                    
 83     }                                                                                
 84 }                                                                                    
 85                                                                                      
 86 1;