Webman-framework

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

About | Overview | Documentation

 

Documentation > Modules and APIs > webman_db_item_view_dynamic

webman_db_item_view_dynamic

 

Description:

Component-type module which provides dynamic control on database table items view/listing.

 

Dependencies:

Webman-framework's Core Modules:

  • DBI_HTML_Map (Composition)
  • HTML_Link_Menu (Composition)
  • HTML_Link_Menu_Paginate (Composition)
  • Select_Option (Composition)
  • TLD_HTML_Map (Composition)

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

 

1. View Output Example

Below is an example of view ouput generated by webman_db_item_view_dynamic component type module. Always refer to this output example as an aid to better understand module documentation explained in the next main sections.


 
2. View Template

The view template is considerable complex since it's used to support dynamic features of database items listing.

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_view_dynamic module is called. The next series of DYNAMIC_CONTENT template-elements (lines 7-9) named db_items_num_begin, db_items_num_end, and db_items_num_total are used as place-holders to provide information about current range of items set being display from all available items in the database table.

The MENU template-element named caption (lines 13-18) is a column headers for item fields to be listed using LIST template-element named main (lines 22-27). The caption MENU template-element will be passed to process_MENU hook function and processed by HTML_Link_Menu core module. It use word patterns menu_item0_ and menu_item1_ as place-holders to display the column captions of item fields mapped by $tld_field_name_1_ and $tld_field_name_3_ (word patterns used inside main LIST template-element). The generated captions text will act as HTML-links which provide options to users to sort database items based on particular field name (column).

Inside the webman_db_item_view_dynamic component-type module, database item list structure is first constructed as Table_List_Data instance via DBI_HTML_Map core module. The aforementioned main LIST template-element will be passed to process_LIST hook function before it's manipulated by TLD_HTML_Map, the core module that responsible to map items from Table_List_Data instance into LIST template-element content structure. Note that there are also $tld_row_class_ and $tld_num_ word patterns enclosed within main LIST template-element. The former is a place-holder for a new column to be added into the list via child module customizations (section 5) to control HTML-table rows view presentation using predefined CSS class. The later is a place-holder for default column name of list item number (related information can be found in section 3, lines 34-46).

The HTML-form (lines 33-51) is used to control the number of items displayed on each list set and the current active list set number. It's actually a control element for database items listing with pagination support.

Inside the form there is fifth DYNAMIC_CONTENT template-element (line 34) named form_hidden_field, 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_view_dynamic module previously.

The text input-element (line 37) enclosed inside CGIHTML template-element is the number of database items to be displayed per page. Template word pattern dynamic_menu_items_ within the MENU template-element named list (line 43) will be processed by HTML_Link_Menu_Paginate core module inside process_MENU hook function. Its main function is to display current set of page index numbers available for users to browse. The SELECT template-element named lsn (line 49) will be processed inside process_SELECT hook function by Select_Option core module to generate HTML-form's select input-element options that is the available number of set of page index numbers. It's used to quickly jump to other set of page index numbers.

  1 <html>                                                                                                            
  2 <body>                                                                                                            
  3 <!-- start_view_ //-->                                                                                            
  4 <!-- dynamic_content_ name=link_path //--> &gt; List Title                                                        
  5 <p />                                                                                                             
  6                                                                                                                   
  7 <!-- dynamic_content_ name=db_items_num_begin //--> -                                                             
  8 <!-- dynamic_content_ name=db_items_num_end //--> of                                                              
  9 <!-- dynamic_content_ name=db_items_num_total //--> Records.                                                      
 10                                                                                                                   
 11 <table border="1">                                                                                                
 12   <!-- start_menu_ name=caption //-->                                                                             
 13   <tr>                                                                                                            
 14     <th>Num.</th>                                                                                                 
 15     <th>menu_item0_</th>                                                                                          
 16     <th>field_caption_2</th>                                                                                      
 17     <th>menu_item1_</th>                                                                                          
 18   </tr>                                                                                                           
 19   <!-- end_menu_ //-->                                                                                            
 20                                                                                                                   
 21   <!-- start_list_ name=main //-->                                                                                
 22   <tr class="$tld_row_class_">                                                                                    
 23     <td align="right">$tld_num_.</td>                                                                             
 24     <td>$tld_field_name_1_</td>                                                                                   
 25     <td>$tld_field_name_2_</td>                                                                                   
 26     <td>$tld_field_name_3_</td>                                                                                   
 27   </tr>                                                                                                           
 28   <!-- end_list_ //-->                                                                                            
 29 </table>                                                                                                          
 30                                                                                                                   
 31 <p />                                                                                                             
 32                                                                                                                   
 33 <form name="tld_view_dynamic" method="post" action="index.cgi">                                                   
 34   <!-- dynamic_content_ name=form_hidden_field //-->                                                              
 35                                                                                                                   
 36   <!-- start_cgihtml_ //-->                                                                                       
 37   Items/List: <input name="inl_param_name" type="text" id="inl_param_name" value="$cgi_inl_param_name_" size="3"> 
 38   <!-- end_cgihtml_ //-->                                                                                         
 39                                                                                                                   
 40   &nbsp;                                                                                                          
 41                                                                                                                   
 42   <!-- start_menu_ name=list //-->                                                                                
 43     dynamic_menu_items_                                                                                           
 44   <!-- end_menu_ //-->                                                                                            
 45   &nbsp;                                                                                                          
 46                                                                                                                   
 47   List Set Num. :                                                                                                 
 48   <select name="lsn" onChange="document.tld_view_dynamic.submit()">                                               
 49     <!-- select_ name=lsn //-->                                                                                   
 50   </select>                                                                                                       
 51 </form>                                                                                                           
 52 <!-- end_view_ //-->                                                                                              
 53 </body>                                                                                                           
 54 </html>                                                                                                           


 
3. Instantiation and Basic Parameter Setting

The most basic setting is to provide the SQL string command to query the items to be listed. It can manually be done by directly passing the SQL string command (line 9) together with other possible word patterns ($cgi_key_field_name_) to map values from the CGI parameters passed to the module. The more convenient and dynamic one is to automatically generate the SQL command by setting the following parameters:

  • Table name of items to be listed (line 11)
  • SQL command to filter the items (lines 13-21)
  • CGI parameter name to represent SQL list order command (line 23)
Generally the above parameter settings will generate the SQL string command in the form of: "select * from $table_name SQL_filter_command SQL_order_command"

The SQL_filter_command is a part of SQL string command generated based on parameter settings via function calls at lines 13-21. The generated SQL string command is a concatenation of strings as follows: "where $filter_field_name='\$cgi_" . $filter_param_name . "_' $filter_additional_keystr"

The SQL_order_command is the end part of SQL string command: "order by \$cgi_" . $order_param_name . "_". The $order_param_name scalar is CGI parameter name that hold current field names used as a keys to sort the items list. This CGI parameter name is set using set_Order_Field_CGI_Var function (line 23) and mainly used as a parameter to store the current active order key-fields passed via item field captions explained in the next paragraph.

Item field captions can be dynamically set to mapped item field names intended to be used as a key-fields for the list order (lines 25-29). Inside the view template, the field captions are rendered as HTML links using place-holders eclosed by MENU template-element (section 2, paragraph 3, code lines 13-18). One single caption might be mapped to more than one order key-fields thus the extra parameter setting (line 32) is required to map the captions with their exact main-field names. These information setting will be used by the module for the logic to display the sequence of order key-fields used if current selected caption is mapped to more than one single order key-fields.

The rest of available parameter setting are used to control other default attributes of the generated dynamic items list. Read the comments included before each function calls for the explanations of their purposes.

  1 $component = new webman_db_item_view_dynamic;                                                                                        
  2                                                                                                                                      
  3 $component->set_CGI($cgi);                                                                                                           
  4 $component->set_DBI_Conn($db_conn);                                                                                                  
  5                                                                                                                                      
  6 ### Option to debug SQL satement generated by the module.                                                                            
  7 #$component->set_SQL_Debug(1);                                                                                                       
  8                                                                                                                                      
  9 #$component->set_SQL("select * from $table_name where key_field_name=\$cgi_key_field_name_ ... order by ...");                       
 10                                                                                                                                      
 11 $component->set_Table_Name($table_name);                                                                                             
 12                                                                                                                                      
 13 #$component->set_Filter_Field_Name($filter_field_name);                                                                              
 14                                                                                                                                      
 15 ### Default is "filter_by_" . $field_name if $field_name                                                                             
 16 ### is set via previous set_Filter_Field_Name functon call                                                                           
 17 #$component->set_Filter_Field_CGI_Var($filter_param_name);                                                                           
 18                                                                                                                                      
 19 ### The possible generic string value for $filter_additional_keystr is:                                                              
 20 ### "[and|or] field_name_1='field_value_1' [and|or] ... [and|or] field_name_n='field_value_n'                                        
 21 #$component->set_Filter_Field_Additional_Keystr($filter_additional_keystr);                                                          
 22                                                                                                                                      
 23 $component->set_Order_Field_CGI_Var($order_param_name);                                                                              
 24                                                                                                                                      
 25 $component->set_Order_Field_Caption("caption_1:...:caption_n");                                                                      
 26                                                                                                                                      
 27 ### It can be 1 or many fields following standard SQL order syntax:                                                                  
 28 ### field_name | field_name desc | field_name_1, ..., field_name_n desc | ...                                                        
 29 $component->set_Order_Field_Name("field_name_1:...:field_name_n");                                                                   
 30                                                                                                                                      
 31 ### It's only [1 to 1] mapping                                                                                                       
 32 #$component->set_Map_Caption_Field("caption_1_ => field_1_, ..., caption_n_ => field_n_");                                           
 33                                                                                                                                      
 34 ### Word pattern as a place-holder for item number in the list.                                                                      
 35 ### Default is "\$tld_num_".                                                                                                         
 36 #$component->set_Row_Num_Text_Pattern($item_number_word_pattern);                                                                    
 37                                                                                                                                      
 38 ### Default index number is 0, that is the first field/column name.                                                                  
 39 #$component->set_Default_Order_Field_Selected($order_field_index_num);                                                               
 40                                                                                                                                      
 41 ### Page index numbers per set. Default is 15                                                                                        
 42 #$component->set_List_Selection_Num($num);                                                                                           
 43                                                                                                                                      
 44 ### Current selected page index number. Default is 1.                                                                                
 45 #$component->set_DB_Items_Set_Num($num);                                                                                             
 46                                                                                                                                      
 47 ### Number of items per page. Default is 10.                                                                                         
 48 #$component->set_DB_Items_View_Num($num);                                                                                            
 49                                                                                                                                      
 50 ### CGI parameter name that hold the value of number of items per page                                                               
 51 ### set by the above set_DB_Items_View_Num function. Default is "inl".                                                               
 52 #$component->set_INL_Var_Name($inl_param_name);                                                                                      
 53                                                                                                                                      
 54 ### CGI parameter name to hold the value of number of                                                                                
 55 ### "Page Index Numbers Set" (PINS) for the purpose PINS's                                                                           
 56 ### quick jump operation. The value will be copied to CGI                                                                            
 57 ### parameter name set by the next set_Dynamic_Menu_Items_Set_Number_Var                                                             
 58 ### function. Default parameter name used is "lsn".                                                                                  
 59 #$component->set_LSN_Var_Name($lsn_param_name);                                                                                      
 60                                                                                                                                      
 61 ### The real CGI parameter name that hold the value of number of                                                                     
 62 ### current active PINS. Default parameter name used is                                                                              
 63 ### "dmisn_" . $cgi->param("task");                                                                                                  
 64 $component->set_Dynamic_Menu_Items_Set_Number_Var($dmisn_param_name);                                                                
 65                                                                                                                                      
 66 ### CGI parameter name that hold the current active page index number.                                                               
 67 ### Default is: "dbisn_" . $cgi->param("task")                                                                                       
 68 $component->set_DB_Items_Set_Num_Var($dbisn_param_name);                                                                             
 69                                                                                                                                      
 70 ### Add CGI parameter names and values to be passed via GET-method                                                                   
 71 ### on each hypertext links generated for item list captions and                                                                     
 72 ### item list page index numbers.                                                                                                    
 73 #$component->set_Additional_GET_Data("get_data_1=get_value_1&...&get_data_n=get_value_n");                                           
 74                                                                                                                                      
 75 ### Add hidden input-element inside the form used to control                                                                         
 76 ### item list pagination.                                                                                                            
 77 #$component->set_Additional_Hidden_POST_Data("post_data_1=post_value_1&...&post_data_n=post_value_n");                               
 78                                                                                                                                      
 79 ### Add CGI parameter names and values to be passed via GET-method                                                                   
 80 ### on each link items of current application's link path.                                                                           
 81 #$component->set_Link_Path_Additional_Get_Data("cgi_var_name_1=cgi_var_value_1_&...&cgi_var_name_n=cgi_var_value_n_");               
 82                                                                                                                                      
 83 $component->set_Template_Default($template_file);                                                                                    
 84                                                                                                                                      


 
4. Component-type Generic Function Calls

 85 if ($component->authenticate) {       
 86     $component->run_Task;             
 87     $component->process_Content;      
 88     $component->end_Task;             
 89 }                                     
 90                                       
 91 my $content = $component->get_Content;


 
5. Child Module for Customization

Most common customizations are to manipulate Table_List_Data instance of the items list (lines 44-46, 54-61, and 70-80), and programmatically modify the SQL string command to support more complex database query logic (line 97).

  1 package child_module_name;                                                    
  2                                                                                                 
  3 use webman_db_item_view_dynamic;                                                                
  4                                                                                                 
  5 @ISA=("webman_db_item_view_dynamic");                                                           
  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 customize_TLD {                                                                             
 32     my $this = shift @_;                                                                        
 33                                                                                                 
 34     my $tld = shift @_;                                                                         
 35                                                                                                 
 36     my $cgi = $this->get_CGI;                                                                   
 37     my $dbu = $this->get_DBU;                                                                   
 38     my $db_conn = $this->get_DB_Conn;                                                           
 39                                                                                                 
 40     my $caller_get_data = $cgi->generate_GET_Data("link_id");                                   
 41                                                                                                 
 42     ### Add new column to represent HTML's CSS class to                                         
 43     ### control the view presentation of HTML-table rows.                                       
 44     $tld->add_Column("row_class");                                                              
 45                                                                                                 
 46     my $row_class = "row_odd";                                                                  
 47                                                                                                 
 48     for (my $i = 0; $i < $tld->get_Row_Num; $i++) {                                             
 49         ### The below implementations assume that the CSS class "row_odd" and                   
 50         ### "row_even" have been already defined and ready to be used inside                    
 51         ### the view template. Refer back to section 2 (the proposed view                       
 52         ### template) and see how the "$tld_row_class_" word pattern act as a                   
 53         ### place-holder inside the main list template-element.                                 
 54         $tld->set_Data($i, "row_class", "$row_class");                                          
 55                                                                                                 
 56         if ($row_class eq "row_odd") {                                                          
 57             $row_class = "row_even";                                                            
 58                                                                                                 
 59         } else {                                                                                
 60             $row_class = "row_odd";                                                             
 61         }                                                                                       
 62                                                                                                 
 63         ### Other possible implementations of customization to manipulate the                   
 64         ### existing column's data of Table_List_Data instance ($tld) to make                   
 65         ### one of its column becomes an active hypertext links. The scalar                     
 66         ### ($get_data) should be a list of additional CGI parameters written                   
 67         ### in GET-data string format ("&param1=value1&param2=$value2&...").                    
 68         ### The $link_properties is a string represent the attributes of the                    
 69         ### HTML <a> tag: <a href="..." $link_properties>...</a>                                
 70         #my $col_name = "...";                                                                  
 71                                                                                                 
 72         #my $get_data = $caller_get_data . "...";                                               
 73         #my $link_properties = "...";                                                           
 74                                                                                                 
 75         #my $tld_data = $tld->get_Data($i, $col_name);                                          
 76                                                                                                 
 77         #$tld_data = "<font color=\"#0099FF\">$tld_data</font>";                                
 78                                                                                                 
 79         #$tld->set_Data($i, $col_name, $tld_data);                                              
 80         #$tld->set_Data_Get_Link($i, $col_name, "index.cgi?$get_data", $link_properties);       
 81                                                                                                 
 82     }                                                                                           
 83                                                                                                 
 84     return $tld;                                                                                
 85 }                                                                                               
 86                                                                                                 
 87 sub customize_SQL { ### so_type_ can be: VIEW, DYNAMIC, LIST, MENU, DBHTML, SELECT, DATAHTML    
 88     my $this = shift @_;                                                                        
 89                                                                                                 
 90     my $cgi = $this->get_CGI;                                                                   
 91     my $dbu = $this->get_DBU;                                                                   
 92     my $db_conn = $this->get_DB_Conn;                                                           
 93                                                                                                 
 94     my $sql = $this->{sql};                                                                     
 95                                                                                                 
 96     ### Next is to customize the $sql string                                                    
 97     #$sql = ...;                                                                                
 98                                                                                                 
 99     return $sql;                                                                                
100 }                                                                                               
101                                                                                                 
102 1;