Webman-framework

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

About | Overview | Documentation

 

Documentation > View-template

View-template

 

Description:

Webman-framework's view-template is simply a standard HTML document comprises a collection of special structured tags constructed using HTML's comment tag: <!-- ... //-->. These special tags are mainly used to split view-template file into several different content parts, known as view-element. The generic form of view-element tags are written as follows:

<!-- element_type_ name=element_name //-->

The element_type_ and element_name tag's properties are view-element's type and name. View-element name (element_name) string mustn't contain any single space characters. View-elements can exist inside the view-template with or without a name. Without a name they can be simply referred back by using their index-type number. However, it's more preferable to give view-elements a unique names, so they can be referred back in more flexible manner.

There are two types of view-element tags that are single or paired. The paired has its generic form as follows:

<!-- start_element_type_ name=element_name //-->

other standard HTML parts and special word patterns goes here...

<!-- end_element_type_ //-->

 

1. View Template Area & VIEW View-element

The <!-- start_view_ //--> and <!-- end_view_ //--> are special paired template tags used to mark the parts of template file content to be processed by the application's component-type modules. In other word they mark the beginning and the ending of line of view-template file to be treated as a view-template area. Other standard HTML parts and framework's sub view-elements must exist inside this view-template area if they are intended to be rendered as a view content of the application.

<html>
<head>...</head>
<body>
<!-- start_view_ //-->

other standard HTML parts and sub view-elements goes here...
<!-- end_view_ //-->
</body>
</html>

Inside the view-template area any standard HTML parts will be treated as a VIEW view-element and will be processed by process_VIEW hook function. Other sub view-elements defined inside the view-template area will be processed by their corresponding hook functions. The example below shows the fragments of view-elements that can be constructed from a single view-template file.
  1 <html>                                   
  2 <head>...</head>                         
  3 <body>                                   
  4 <!-- start_view_ //-->                   
  5                                          
  6 <h1>WebDev Inc.</h1>                     
  7 <hr />                                   
  8                                          
  9 <!-- start_menu_ name=main_link //-->    
 10 <p>Main Links:</p>                       
 11 menu_item0_ | menu_item1_ | menu_item2_  
 12 <!-- end_menu_ //-->                     
 13                                          
 14 Our organization provide services to ... 
 15 <hr />                                   
 16 Copyright 2012 WebDev Org.               
 17                                          
 18 <!-- end_view_ //-->                     
 19 </body>                                  
 20 </html>                                  

There are three view-elements exist inside the above template file as follows:

Code LinesElement TypeIndex-type Num.Element Name
05 - 08 VIEW 0  
10 - 11 MENU 1 main_link
13 - 17 VIEW 2  

All of sub view-elements that can be included inside the view-template area are described in section 3 and section 4.


 
2. Component Designation & Hook Function Implementation

View-template files are normally designated to and processed by specific component-type modules (CGI_Component::webman_CGI_component based modules). The designation of template file to these type of modules can be done by applying template file naming convention following framework's "Convention over Configurations" (CoC) style. The CoC proposed that, for component-type module component_name.pm the default view-template file name can be template_component_name.html or component_name.html. The former naming style has the privilege over the latter and the component itself will automatically search an existing file using these naming conventions. To manually assign template file to specific component, the component's set_Template_File(...) generic function can be used. The implementation can be done inside component's process_Content{...} function as below:

sub process_Content {
    $this = shift @_;

    my $cgi = $this->get_CGI;
    my $dbu = $this->get_DBU;
    my $db_conn = $this->get_DB_Conn;

    ### Option to change default template view.
    if (some condition...) {
        $this->set_Template_File("other_template_file.html");
    }

    ### The heart of "Template Method" design pattern that call "hook"
    ### functions to process and manipulate view's view-elements
    $this->SUPER::process_Content;
}

Inside the component-type modules each view-elements are binded to specific hook functions through the implementations of "Inversion of Control" (IoC) mechanism using "Template_Method" design pattern. Developers doesn't need to know how these hook methods should be called at runtime, they only need to override them to process and manipulate the view-element before return the content result back to the component. Below is the generic skeleton code of hook function implementation.
### The skeleton of "hook" function to be redefined to process
### view-elements content. TE_TYPE can be: VIEW, DYNAMIC, SELECT, MENU,
### DBHTML, LIST, DATAHTML, or CGIHTML.
sub process_TE_TYPE {
    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;

    ### Process view-elements by referring
    ### to their name.
    if ($te_type_name eq "???") {
        ...
    }

    ### Option to process view-elements by referring
    ### to their index-type number
    #if ($te_type_num == ???) {
    #    ...
    #}

    $this->add_Content($te_content);
}



 
3. Single View-element Tags

Single template-tags will become a content place-holder themselves. They are normally used as a place-holder for other complex-structured contents generated by other component-type modules.

 

3.1 DYNAMIC_CONTENT View-element

Inside framework's main controller (webman_main), DYNAMIC_CONTENT has been used as main view-element to be processed and linked to application's main link structure. For each link-nodes, DYNAMIC_CONTENT view-element names are used as references by main controller to run other application's component-type modules.

<!-- dynamic_content_ name=element_name //-->

Inside the main controller and other component-type modules DYNAMIC_CONTENT view-elements are passed to and handled by process_DYNAMIC hook function.

 

3.2 SELECT View-element

It should no be used directly by developers since it exist as default view-element used by framework's standard component-type modules.

<!-- select_ name=element_name //-->

Inside component-type modules SELECT view-elements are passed to and handled by process_SELECT hook function.

 


 
4. Paired View-element Tags

Paired view-element tags normally contains special word patterns act as a content place-holder for application data. Its contents (special word patterns and other HTML parts) are normally passed to other framework's core modules to be processed/manipulated before return back the result to current component which the view-template file was designated.

 

4.1 MENU View-element

View-element used to render the application menu or precisely the HTML links to call application resources/services via HTTP-GET method approach. It might content the template word patterns menu_itemidx_ or dynamic_menu_items_ as its content place-holder. These options of word patterns are depends on the core modules used to process the view-element's content (HTML_Link_Menu or HTML_Link_Menu_Paginate).

MENU view-element to be processed by HTML_Link_Menu core module:

<!-- start_menu_ name=element_name //-->
    menu_item0_ | menu_item1_ | ...

<!-- end_menu_ //-->

MENU view-element to be processed by HTML_Link_Menu_Paginate core module:

<!-- start_menu_ name=element_name //-->

    dynamic_menu_items_

<!-- end_menu_ //-->

Inside component-type modules MENU view-elements are passed to and handled by process_MENU hook function.

 

4.2 DBHTML View-element

View-element used to map database table fields value inside the view template and then render them as application view content. Inside the hook function, DBHTML view-element content is passed to and manipulated by DBI_HTML_Map core module. The word pattern $db_field_name_ is used to map database table field name to be viewed.

<!-- start_dbhtml_ name=element_name //-->

Field Caption: $db_field_name_

<!-- end_dbhtml_ //-->

Inside component-type modules DBHTML view-elements are passed to and handled by process_DBHTML hook function.

 

4.3 LIST View-element

View-element that by convention proposed to be used as content place-holder for application's data dynamically handled by Table_List_Data core module. Inside the hook function, LIST view-element content is passed to and manipulated by TLD_HTML_Map core module. TLD_HTML_Map instance will have Table_List_Data instance as one of its basic parameter setting (member instance via aggregation). The word pattern $tld_column_name_ is used to map column names available from inside Table_List_Data instance.

<!-- start_list_ name=element_name //-->

Column Caption: $tld_column_name_

<!-- end_list_ //-->

Inside component-type modules LIST view-elements are passed to and handled by process_LIST hook function.

 

4.4 DATAHTML View-element

Prior the availability of CGIHTML view-element, DATAHTML view-element has been mainly used to map CGI parameters inside the view-template files and render them as application view content. After CGIHTML view-element was introduced, it still remains as one of standard framework's view-element since it has been extensively used as a standard view-element to be processed by database related component-type modules to support dynamic and interactive view features for table items insert/update/delete operations.

Word patterns inside DATAHTML view-element are normally the mapping of database table field (names and values) to an HTML-form's input elements. As shown below, $db_field_name and $db_field_name_ are two different things. The former is the input element name represents database table field name to be passed as one of CGI parameters and the later is the place-holder to render the coresspond CGI parameter value. HTML-form input elements are named in the form of $db_field_name to adhere the naming convention requirements imposed by other core module (HTML_DB_Map) that is responsible for the real database operations inside the framework's database related component-type modules.

<!-- start_datahtml_ name=element_name //-->

<form method="POST" action="./index.cgi">

Field Caption: <input name="$db_field_name" type="text" value="$db_field_name_">

<input name="button_submit" type="submit" id="button_submit" value="Submit"/>

</form>

<!-- end_datahtml_ //-->

Inside component-type modules DATAHTML view-elements are passed to and handled by process_DATAHTML hook function.

 

4.5 CGIHTML View-element

View-element used to map CGI variable/parameter names and render their values inside view-template files. Word patterns used as place-holder to map CGI variable/parameter values are in the form of $cgi_var_name_.

<!-- start_cgihtml_ name=element_name //-->

CGI Var. Caption: $cgi_var_name_

<!-- end_cgihtml_ //-->

CGIHTML is the only view-element type that can be nested inside other paired view-element tags. Inside the application components, nested CGIHTML view-element have the priority for its hook function to be called first before its parent hook function. Below is the generic form of how CGIHTML view-element which might be nested inside other view-element (DBHTML).

<!-- start_dbhtml_ name=element_name //-->

Field Caption: $db_field_name_

<!-- start_cgihtml_ name=element_name //-->

CGI Var. Caption: $cgi_var_name_

<!-- end_cgihtml_ //-->

<!-- end_dbhtml_ //-->

Inside component-type modules CGIHTML view-elements are passed to and handled by process_CGIHTML hook function. However, in most cases, it does not requires overriding implementation by developers since it already implemented inside CGI_Component core module (the most top base-module of component-type modules).