Webman-framework

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

About | Overview | Documentation

 

Documentation > Modules and APIs > HTML_Link_Menu_Paginate

HTML_Link_Menu_Paginate

 

Description:

The core module to dynamically generate web application menu (with menu items pagination support) using standard HTML hypertext links. The hypertext links generated are mainly used to provide users an access points to application services via HTTP-GET method.

 

Dependencies:

Webman-framework's Core Modules:

  • HTML_Link_Menu (Inheritance)

 

1. View Template

Following Webman-framework's "Convention over Configuration" (CoC) the view template to render HTML_Link_Menu_Paginate result content is simply a MENU template-element with dynamic_menu_items_ word pattern as its content place-holder. The template element can be later manipulated inside the process_MENU hook function (see section 4).

<html>
<body>
<!-- start_view_ //-->
<!-- start_menu_ name=numspell //-->
dynamic_menu_items_
<!-- end_menu_ //-->
<!-- end_view_ //-->
</body>
</html>



 
2. Instantiation and Basic Parameter Setting


my $html_menu = new HTML_Link_Menu_Paginate;


2.1 Links, Captions, and Attributes.

The next two functions are mandatorily to be called just after the instantiation or the module can't generate the intended menu links. The @menu_items is an array of the link captions while @menu_links is an array of the links attributes. The link attributes normally a CGI CGI parameters passed via HTTP-GET method. The link attribute should be the uniques one which can't be automatically generated by the module itself (see section 2.3).

$html_menu->set_Menu_Items(@menu_items);
$html_menu->set_Menu_Links(@menu_links);


2.2 Link Items Pagination.

Pagination support for large number of link items can be done by passing $num_view and $num_view arguments to the next two functions. The $num_set argument normally can be retrieved from $cgi->param($item_set_ref_name). Read section 2.3 for more information about the $item_set_ref_name argument.

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


2.3 Basic and Additional Links Attributes

Function to automatically set the basic standard link items attributes. The script name "index.cgi" is the default CGI main script name in Webman-framework. The arguments $link_ref_name and $item_set_ref_name are the link attributes name used to refer to current selected link item name and link items set number. Both will exist as CGI parameters passed via HTTP-GET method.

$html_menu->set_Auto_Menu_Links("index.cgi", $link_ref_name, $item_set_ref_name);

Other additional GET-data attributes which are indentical for all link items can be added using the next function.
$html_menu->add_GET_Data_Links_Source("param_1=value_1&...&param_n=value_n");


2.4 Current Selected Link Item

The argument $current_selected_link is the current selected link item name. Using the previous setting (section 2.3 above) it's possible to have its value from $cgi->param($link_ref_name) function call.

$html_menu->set_Active_Menu_Item($current_selected_link);


2.5 Link Items Separator and Next/Previous Navigation Tags

The default separator, next, and previous tags are "|", ">>", and "<<".

$html_menu->set_Separator_Tag($tag_separator);
$html_menu->set_Next_Tag($tag_next);
$html_menu->set_Previous_Tag($tag_previous);


2.6 Unselected Links Text Color

$html_menu->set_Non_Selected_Link_Color($color_link_active);



 
3. Processing Template Element Content

$html_menu->set_Menu_Template_Content($te_content);
my $content = $html_menu->get_Menu;
$html_menu->reset_Menu;

The $html_menu->reset_Menu function call is an option to reset the link items captions and their attributes previously set in section 2.1.

 
4. Implementation Inside Hook Function

In most cases, link menu items generation from application's main link structure does not requires this type of hook function implementatiom since it has been conveniently supported by webman_dynamic_links framework's component type module.

sub process_MENU { 
    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;
    
    ### The "link_id" argument is Webman-framework's standard CGI parameter 
    ### name that refer to current link item selected from the application 
    ### main link structure. It will be passed as an additional GET-data to  
    ### dynamic link items to be generated below. So, each click on them will  
    ### point back to current selected application's main link item.
    my $link_id = $cgi->param("link_id");
    
    if ($te_type_name eq "numspell") {
        ### Set menu's link items and their unique attributes.
        my @menu_items = (1, 2, 3, 4, 5, 6, 7, 8);
        my @menu_links = ("spell=one", "spell=two", "spell=three", "spell=four", 
                          "spell=five", "spell=six", "spell=seven", "spell=eight");    

        ### Start using module to generate dynamic links.
        my $html_menu = new HTML_Link_Menu_Paginate;

        $html_menu->set_Menu_Items(@menu_items);
        $html_menu->set_Menu_Links(@menu_links);

        $html_menu->set_Items_View_Num(3);
        $html_menu->set_Items_Set_Num($cgi->param("dmisn"));

        ### num = number, dmisn = dynamic_menu_item_set_number
        $html_menu->set_Auto_Menu_Links("index.cgi", "num", "dmisn");
        $html_menu->add_GET_Data_Links_Source("link_id=$link_id");

        $html_menu->set_Active_Menu_Item($cgi->param("num"));

        $html_menu->set_Menu_Template_Content($te_content);
        my $content = $html_menu->get_Menu;

        $this->add_Content($content);
    }
}