Webman-framework

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

About | Overview | Documentation

 

Documentation > Modules and APIs > DBI_HTML_Map

DBI_HTML_Map

 

Description:

The core module used to map database table fields and render their values inside the view template. This module can also be used to create and return Table_List_Data module instance that dynamically represents the data structure of rows and columns of database items. In fact, this module was mainly used to generate Table_List_Data instance inside most of its clients (webman_db_item_update, webman_db_item_delete, webman_db_item_view_dynamic, webman_db_item_update_multirows, and webman_db_item_delete_multirows). Currently, there is only single component type module (webman_db_item_view) using it to directly mapping database table fields and values into the view template.

 

Dependencies:

Webman-framework's Core Modules:

  • Table_List_Data (Composition)

 

1. View Template

The paired template tags <!-- start_dbhtml_ name=db_field_view //--> and <!-- end_dbhtml_ //--> are used to mark the parts of DBHTML template-element (lines 17-23) to be processed by the DBI_HTML_Map module. The database table field names are mapped using template word patterns $db_field_name_1, ..., till $db_field_name_n, adhere mapping naming convention imposed by DBI_HTML_Map module itself.

  1 <html>                                                    
  2 <body>                                                    
  3 <!-- start_view_ //-->                                    
  4 <!-- dynamic_content_ name=link_path //--> &gt; List Title
  5 <p />                                                     
  6                                                           
  7 <table border="1">                                        
  8   <tr>                                                    
  9     <th>Num.</th>                                         
 10     <th>field_caption_1</th>                              
 11     <th>field_caption_2</th>                              
 12     ...                                                   
 13     <th>field_caption_n</th>                              
 14   </tr>                                                   
 15                                                           
 16   <!-- start_dbhtml_ name=db_field_view //-->             
 17   <tr>                                                    
 18     <td align="right">$num_.</td>                         
 19     <td>$db_field_name_1_</td>                            
 20     <td>$db_field_name_2_</td>                            
 21     ...                                                   
 22     <td>$db_field_name_n_</td>                            
 23   </tr>                                                   
 24   <!-- end_dbhtml_ //-->                                  
 25 </table>                                                  
 26                                                           
 27 <!-- end_view_ //-->                                      
 28 </body>                                                   
 29 </html>                                                   

In the context of Webman-framework's component implementation, the above DBHTML template-element will be passed to and processed inside process_DBHTML hook function (see section 6).

 
2. Instantiation and Basic Parameter Setting

The passed arguments $cgi and $db_conn are other Webman-framework core modules instances. The $cgi is an instance of GMM_CGI module and the $db_conn is an instance of database connection created using DBI module. The $sql is a raw SQL statement used to query items from the database table.

my $dbihtml = new DBI_HTML_Map;

$dbihtml->set_DBI_Conn($db_conn);
$dbihtml->set_SQL($sql);

$dbihtml->set_Items_View_Num($num_view);
$dbihtml->set_Items_Set_Num($num_set);

The $num_view can be used to limit the item's view rows number and does requires $num_set to determine the set number of items to be viewed since the returned items have been splited into several set of rows. These two arguments actually provide pagination control on database item listing.

 
3. Processing Template Element Content

$dbihtml->set_HTML_Code($te_content);
my $content = $dbihtml->get_HTML_Code;



 
4. Table_List_Data Instance

Function to help the creation of Table_List_Data module instance.

my $tld = $dbihtml->get_Table_List_Data;



 
5. Database Query Result Information

### Get database error for the given query ($sql) in section 2.  
my $error = $dbihtml->get_DB_Error_Message;

### Total of item row number returned.
my $total_item = $dbihtml->get_Items_Num;

### Total item set number that is the rounded up of 
### [$num_view (in section 2) / $total_item] even if 
### the decimal point is < 0.5
my $total_set = $dbihtml->get_Total_Items_Set_Num;



 
6. Implementation Inside Hook Function

sub process_DBHTML { 
    my $this = shift @_;
    my $te = shift @_;

    my $cgi = $this->get_CGI;
    my $dbu = $this->get_DBU;
    my $db_conn = $this->get_DB_Conn;
    
    my $te_content = $te->get_Content;
    my $te_type_num = $te->get_Type_Num;
    my $te_type_name = $te->get_Name;
    
    ### Start process template-element' content.
    if ($te_type_name eq "db_field_view") {
        my $dbihtml = new DBI_HTML_Map;
        
        $dbihtml->set_DBI_Conn($db_conn);
        $dbihtml->set_SQL($this->{sql});
        #$dbihtml->set_Items_View_Num($num_view);
        #$dbihtml->set_Items_Set_Num($num_set);    
        $dbihtml->set_HTML_Code($te_content);
    
        my $content = $dbihtml->get_HTML_Code;
    
        if ($dbihtml->get_DB_Error_Message ne "") {
            $cgi->add_Debug_Text("Database Error: " . $dbihtml->get_DB_Error_Message, __FILE__, __LINE__, "DATABASE");
        }    
    
        if ($dbihtml->get_Items_Num > 0) {
            $this->add_Content($content);
        }
    }
}