Webman-framework

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

About | Overview | Documentation

 

Documentation > Modules and APIs > HTML_DB_Map

HTML_DB_Map

 

Description:

The core module to map CGI parameters to database table fields for insert/update operations. The CGI parameters are normally passed by HTML form input elements from the view template.

This module has been intensively used inside the following Webman-framework's component-type modules: webman_db_item_insert, webman_db_item_update, webman_db_item_insert_multirows, webman_db_item_update_multirows, and webman_text2db_map.

 

Dependencies:

Webman-framework's Core Modules:

  • DB_Utilities (Composition)

 

1. View Template

The view template with HTML-form input elements to pass CGI parameters to be mapped to database table fields. Form input elements to be mapped to database table fields are named using the naming convention as follows: $db_field_name_1, ..., $db_field_name_n

<html>
<body>
<!-- start_view_ //-->
<form method="POST" action="./index.cgi">
  field_caption_1 : <input name="$db_field_name_1" type="text"><p />
  ...
  field_caption_n : <input name="$db_field_name_n" type="text"><p />
  <input name="button_submit" type="submit" id="button_submit" value="Submit"/>
</form>
<!-- end_view_ //-->
</body>
</html>

On form submission, designated component-type module should process the passed CGI parameters for insert/update operations using HTML_DB_Map module inside the run_Task function (see section 6). This function becomes a hook function that is called inside application controller following component's functions calling procedures described in GGI_Component.

 
2. Instantiation and Basic Parameter Setting

my $htmldb = new HTML_DB_Map;

$htmldb->set_CGI($cgi);
$htmldb->set_DBI_Conn($db_conn);
$htmldb->set_Table($table_name);



 
3. Fields Mapping Exceptions

By default HTML_DB_Map module will extract all CGI parameters with the name patterns: $db_field_name_1, ..., $db_field_name_n to be mapped to table fields for insert/update operations. Use the next function to provide an exceptions (each field name are separated by single spaces).

$htmldb->set_Exceptional_Fields("field_name_1 ... field_name_n"); 



 
4. Insert/Update Access Authentication

Set basic information for insert/update operations access privilege control implementation. User information to be passed are current user name ($login_name) and groups assigned to the user (\@groups) which is a reference to an array. The $db_item_auth_table_name scalar is an application's insert/update operations access privilege table that normally has a name in the form of "webman_appname_db_item_auth".

$htmldb->set_DB_Item_Auth_Info($login_name, \@groups, $db_item_auth_table_name);



 
5. Insert/Update Implementation

The argument $exec_mode is an option of SQL statement execution for insert/update operations. It can be set to '0' (to only prepare the SQL statement) and if ignored the default is '1' (really execute the SQL statement).

5.1 Insert Operation.

$htmldb->insert_Table($exec_mode);


5.2 Update Operation (option 1).
$htmldb->update_Table("key_1 ... key_n", "val_1 ... val_n", $exec_mode);


5.3 Update Operation (option 2).

The $keys_str is normally a complex SQL update keys string which is not supported by the simplified ("key_1 ... key_n", "val_1 ... val_n") update keys and values mapping used in the first option.

$htmldb->set_Update_Keys_Str($keys_str);
$htmldb->update_Table(undef, undef, $exec_mode);


5.4 Insert/Update Operations Errors.

Get database errors correspond to insert/update operations. It's applicable for both SQL execution options (at the preparation level or the real execution).

my $error_opr = $htmldb->get_DB_Error_Message;


5.4 Insert/Update Authentication Errors.

Get insert/update operations errors caused by privilege access control apllied to database item fields. It requires user and groups information setting as described in section 4.

my $error_auth = $htmldb->get_Auth_Error_Message;




 
6. Implementation Inside Hook Function

sub run_Task {
    my $this = shift @_;
    
    my $cgi = $this->get_CGI;
    my $dbu = $this->get_DBU;
    my $db_conn = $this->get_DB_Conn;
    
    my $login_name = $this->get_User_Login;
    my @groups = $this->get_User_Groups;
    
    my $table_name = "???";
    my $db_item_auth_table_name = "???";
    
    my $htmldb = new HTML_DB_Map;

    $htmldb->set_CGI($cgi);
    $htmldb->set_DBI_Conn($db_conn);
    $htmldb->set_Table($table_name);
    $htmldb->set_DB_Item_Auth_Info($login_name, \@groups, $db_item_auth_table_name);
    
    $htmldb->insert_Table;
    
    if ($htmldb->get_DB_Error_Message ne "") {
        $cgi->add_Debug_Text($htmldb->get_DB_Error_Message, __FILE__, __LINE__, "DATABASE");
    }
    
    if ($htmldb->get_Auth_Error_Message ne "") {
        $cgi->add_Debug_Text($htmldb->get_Auth_Error_Message, __FILE__, __LINE__, "DATABASE");
    }    
}