Webman-framework

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

About | Overview | Documentation

 

Documentation > Modules and APIs > CGI_Component

CGI_Component

 

Description:

The core module used as a base module by webman_CGI_component module. It provide generic functions via inheritance for webman_CGI_component module and its other sub-modules/clients to run as a framework's component following Webman-framework's component specifications.

Below are the basics Webman-framework's component specifications.

  1. The major tasks of component is to internally solved the most generics problems in web application development involving the handling and managing of CGI-data, link structure, business logic and view (presentation) integrations, application resource access control, and coordinating access to other support elements such as database connection, CGI library, helper tools, etc.

  2. Provides design that help developers separate the coding of business logic and content presentation at component function level.

  3. To handle content presentation the components themselves implements the logical engine to extract template-elements from the application view template assigned to them. Application view template is standard HTML document written following view template structure specified by the framework.

  4. Components can be used either as a black-box or white-box objects to handle business logic and view. For white-box approach, the components implementing "Template Method" software design pattern.

  5. The components provide an internal mechanism to set component's parameters & values (module member functions) at application runtime by first registering the parameters & values inside the database (real implementation is done inside webman_CGI_component module).

  6. Internally provide access control facilities at component name level.

  7. Internally provide access control facilities at application link structure level (real implementation is done inside webman_CGI_component module).

  8. Automatically handle CGI-data content presentation inside view template without need CGI's template-elements manipulation by developers via function overriding using "Template Method" approach.

  9. At application runtime, component's functions, by their generic main tasks must be called in an order as follows: setting up CGI and database connection instances, component's specific parameters setting, access control authentication (link structure and component's name itself), run main business logic, process view template, run end-task function, and finally get the HTML content result. These flow of tasks are by default enforced inside framework's main controller (webman_main).

The next sections (1 and 2) describe how some of the tasks order specified in 9 could be implemented.

 

Dependencies:

Webman-framework's Core Modules:

  • DB_Utilities (Composition)
  • CGI_HTML_Map (Composition)
  • GMM_CGI (Aggregation)
  • Session (Composition)
  • Template_Element_Extractor (Composition)
Please note that the above module list are in the context of they are directly used by CGI_Component module itself. There are other core modules included but they are used in the context of the CGI_Component's clients. Below are the complete list of these modules:

DB_HTML_Map, HTML_DB_Map, Text_DB_Map, DBI_HTML_Map, Data_HTML_Map, Select_Option, Checkbox_Selection, HTML_Table_Menu, HTML_Link_Menu, HTML_Dynamic_Link_Menu, HTML_Dynamic_Numbered_Link_Menu, Static_Content, Link_Structure_Content_Info, HTML_Object_Separator, Table_List_Data, TLD_HTML_Map, HTML_Link_Path, Link_Node, Calendar.

 

1. 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 CPAN's DBI module.

my $component = new CGI_Component;

$component->set_CGI($cgi);
$component->set_DBI_Conn($db_conn);



 
2. Component-type Generic Functions Call

Other generic functions to be called following Webman-framework specificatons to run the module as a framework's component.

### Start set component specific parameters
#$component->set_???;

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

my $content = $component->get_Content;



 
3. Child Module for Customization

Basic skeleton code to use CGI_Component as a base module. Generally there are three main types of implementations or customizations as follows:

  • Handling and processing system/environment resources, application's domain data access and manipulation (mostly involving the database), and preparation of view's parameters or view's data-structure instances. All of these should be done inside the implementation of run_Task hook function.
  • Integrating view's parameters or view's data-structure instances with their coresspond template-elements through the implementation of template hook functions (process_TE_TYPE).
  • Other relevant tasks of ending component-type module's runtime such as releasing resources, CGI parameters cache clearance, page redirect, etc. (inside end_Task hook function)
  1 package child_module_name;                            
  2 require CGI_Component;                                                  
  3                                                                         
  4 @ISA=("CGI_Component");                                                 
  5                                                                         
  6 sub new {                                                               
  7     my $class = shift;                                                  
  8                                                                         
  9     my $this = $class->SUPER::new();                                    
 10                                                                         
 11     #$this->set_Debug_Mode(1, 1);                                       
 12                                                                         
 13     bless $this, $class;                                                
 14                                                                         
 15     return $this;                                                       
 16 }                                                                       
 17                                                                         
 18 sub get_Name {                                                          
 19     my $this = shift @_;                                                
 20                                                                         
 21     return __PACKAGE__;                                                 
 22 }                                                                       
 23                                                                         
 24 sub get_Name_Full {                                                     
 25     my $this = shift @_;                                                
 26                                                                         
 27     return $this->SUPER::get_Name_Full . "::" . __PACKAGE__;            
 28 }                                                                       
 29                                                                         
 30 sub run_Task {                                                          
 31     my $this = shift @_;                                                
 32                                                                         
 33     my $cgi = $this->get_CGI;                                           
 34     my $dbu = $this->get_DBU;                                           
 35     my $db_conn = $this->get_DB_Conn;                                   
 36                                                                         
 37     my $login_name = $this->get_User_Login;                             
 38     my @groups = $this->get_User_Groups;                                
 39                                                                         
 40     ### Skeleton code to check if current user's groups are match with  
 41     ### specific intended group name.                                   
 42     #my $group_name = "???";                                            
 43     #my $match_group = $this->match_Group($group_name, @groups);        
 44 }                                                                       
 45                                                                         
 46 sub process_Content {                                                   
 47     $this = shift @_;                                                   
 48                                                                         
 49     my $cgi = $this->get_CGI;                                           
 50     my $db_conn = $this->get_DB_Conn;                                   
 51     my $db_interface = $this->get_DB_Interface;                         
 52                                                                         
 53     ### Option to change default template view.                         
 54     #if (some condition...) {                                           
 55     #    $this->set_Template_File("other_template_file.html");          
 56     #}                                                                  
 57                                                                         
 58     ### The heart of "Template Method" design pattern that call "hook"  
 59     ### functions to process and manipulate view's template-elements    
 60     $this->SUPER::process_Content;                                      
 61 }                                                                       
 62                                                                         
 63 ### The skeleton of "hook" function to be redefined to process          
 64 ### template-elements content. TE_TYPE can be: VIEW,  
 65 ### DYNAMIC, LIST, MENU, DBHTML, SELECT, DATAHTML, or CGIHTML.          
 66 sub process_TE_TYPE {                                 
 67     my $this = shift @_;                                                
 68     my $te = 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 $te_content = $te->get_Content;                                  
 75     my $te_type_num = $te->get_Type_Num;                                
 76     my $te_type_name = $te->get_Name;                                   
 77                                                                         
 78     ### Start process template-element content.                         
 79     #???                                                                
 80                                                                         
 81     $this->add_Content($te_content);                                    
 82 }                                                                       
 83                                                                         
 84 sub end_Task {                                                          
 85     my $this = shift @_;                                                
 86                                                                         
 87     my $cgi = $this->get_CGI;                                           
 88     my $dbu = $this->get_DBU;                                           
 89     my $db_conn = $this->get_DB_Conn;                                   
 90                                                                         
 91     my $login_name = $this->get_User_Login;                             
 92     my @groups = $this->get_User_Groups;                                
 93                                                                         
 94     ### Skeleton code to check if current user's groups are match with  
 95     ### specific intended group name.                                   
 96     #my $group_name = "???";                                            
 97     #my $match_group = $this->match_Group($group_name, @groups);        
 98                                                                         
 99     ### It's mandatory to call this for multi phases modules            
100     ### to reset some of the no longer required CGI data.               
101     $this->SUPER::end_Task;                                             
102 }                                                                       
103                                                                         
104 1;