Webman-framework

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

About | Overview | Documentation

 

Documentation > Tutorial > 4. Link structure implementation

Link structure implementation

 

In the previous section, the "template_main.html" view-template file has been assigned as a main view-template of the application. It's done at "Home" node that act as an entry point to the application via reference to "webman_main" module. It's a MAIN_CONTROLLER type reference used to assign main view-template file to application main-controller (mygb.pm) via "template_default" parameter setting. Though "webman_main" module might be used as a base module for other application main-controller but all parameter settings applied to "webman_main" module here are limited to mygb's application only. This is due to the fact that the parameter settings applied is not hard-coded inside the "webman_main" module itself but dynamically loaded from application database table and further scoped to "Home" node and its child nodes.

After understanding the basic concepts of how application link structure, main controller, and view-template are integrated together, the next step is to look how application contents could be arranged inside the view-template. Below is the content of "template_main.html" view-template file.

  1 <html>                                                                   
  2 <head>                                                                   
  3 <title>Untitled Document</title>                                         
  4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> 
  5 </head>                                                                  
  6 <body>                                                                   
  7 <!-- start_view_ //-->                                                   
  8 <table border="1" width="100%">                                          
  9   <tr>                                                                   
 10     <td>                                                                 
 11       <div align="center"><h2>$app_name_ Application Header</h2></div>   
 12       <div align="right"><b>You are login as:</b> $user_full_name_ </div>
 13     </td>                                                                
 14   </tr>                                                                  
 15                                                                          
 16   <tr height="30">                                                       
 17     <td align="center">                                                  
 18       <!-- dynamic_content_ name=link_main //-->                         
 19     </td>                                                                
 20   </tr>                                                                  
 21                                                                          
 22   <tr>                                                                   
 23     <td align="center" valign="top">                                     
 24       <br />                                                             
 25       <!-- dynamic_content_ name=content_main //-->                      
 26     </td>                                                                
 27   </tr>                                                                  
 28                                                                          
 29   <tr height="30">                                                       
 30     <td align="center">                                                  
 31       Copyright &copy; 2010 - $current_year_ Your organization name.     
 32     </td>                                                                
 33   </tr>                                                                  
 34 </table>                                                                 
 35                                                                          
 36 <div id="popup_div_onmove" class="popup" onMouseOut="popup_hide(this);"> 
 37 </div>                                                                   
 38                                                                          
 39 <div id="popup_div_onclick" class="popup_onclick">                       
 40 </div>                                                                   
 41 <!-- end_view_ //-->                                                     
 42 </body>                                                                  
 43 </html>                                                                  

The "template_main.html" view-template file 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 template-element. Inside the above "template_main.html" template file the <!-- start_view_ //--> and <!-- end_view_ //--> paired template tags (lines 7 and 41) are used to mark the part of view content to be rendered by the application. Within the rendered view section there are two DYNAMIC_CONTENT template-elements named as link_main and content_main. DYNAMIC_CONTENT template-element is placed inside the view content using the <!-- dynamic_content_ name=element_name //--> single template tag. It's a good practice to give a unique names to each DYNAMIC_CONTENT template-elements inside the view-template though not doing so will not cause any errors and the template-elements can still be referred back using their index number. Read the view-template documentation for detailed explanations on framework's view-template structure, elements, and its implementations.

As shown below, assigning "template_main.html" view-template file to "Home" node's "webman_main" MAIN_CONTROLLER type reference will make link_main and content_main DYNAMIC_CONTENT template-elements available as "Dynamic Content ID" selections under "Name" sub-category for DYNAMIC_MODULE and STATIC_FILE type references.

 

Apply the form input element selections as shown above and then click the "Add" button. The "webman_dynamic_links" component-type module should now be added as DYNAMIC_MODULE type reference to "Home" node as below.

 

In the above "Home" node's reference setting, "webman_dynamic_links" DYNAMIC_MODULE type reference has been associated with link_main DYNAMIC_CONTENT template-element. The link_main DYNAMIC_CONTENT template-element will act as a placeholder for content to be generated by "webman_dynamic_links" module. The next step is to set the parameter values for "webman_dynamic_links" module so it can generate and render application main links which are the child nodes of the "Home" node itself. For that purpose, we should first understand the whole link structure of the application. Below is the current hierarchical link structure of mygb application.
  1                          Root                                   
  2                           |                                     
  3                  -------------------                            
  4                 |         |         |                           
  5               Home  json_entties_  test_  <--- Link Path Level 0
  6                 |                                               
  7    ----------------------------                                 
  8   |         |           |      |                                
  9 About  Sign Guestbook  List  Admin        <--- Link Path Level 1

The "Root" node is a virtual node and will never be visible inside the application's pages. The framework propose that only "Home" node and its child nodes should be made visible by the application. For that reason, application's main links and its sub links should be added under the "Home" node and this is what has been done to the main links of mygb application. From the above hierarchical link structure, they are all at the link path level 1.

Still in the above ADT's "Link Structure/Reference" page section for "Home" node's update reference, at the "Operations" column, click the "Set Param[00]" link for "webman_dynamic_links" and the set the parameter settings as follows.

 

Do notice that the parameter name "link_path_level" is set to "1" which is the link path level of mygb application's main link nodes. Don't have to worried about the view-template for "webman_dynamic_links" module since it can assign itself a view-template file named "template_webman_dynamic_links.html" which is already included by the framework's distribution. Do check all available included view-template files inside the E:\wmbase\public_html\cgi-bin\webman\mygb directory path. Also revise how component-type module like "webman_dynamic_links" can assign itself a view-template file following the framework's CoC as explained in the section 3 of this tutorial ( Main view-template assignment) .

Refresh browser window/tab for mygb application and it should now display the application main link nodes exactly at the intended placeholder (link_main DYNAMIC_CONTENT template-element). Also note how the "|" character that set via "link_separator_tag" parameter name is arranged as a part of the content generated by "webman_dynamic_links" module.

 

As demonstrated above, when there is no link ID is supplied as a CGI parameter to the application, the "Home" node will by default automatically selected but none for its child nodes. It's nice to have one of these child nodes which act as a main links to the application has the same behaviour as its parent the "Home" node.

At the ADT's "Link Structure/Reference" page section, list all child nodes under "Home" node and click the "Update Info." operation link for "About" node. Set its "Auto Selected" option to "Yes" as below.

 

Click the "Submit" button to apply the change and the ADT's "Link Structure/Reference" page section will list back all child nodes under the "Home" node with "About" node has been changed to an "Auto Selected" node as below.

 

Both "Home" node and its child node "About" is now an auto selected nodes. When users access to the application without supplying any link ID information, the application will by default assume that the link ID for "About" node is selected. The "About" node will be used to display a simple welcome message to the users. It can easily be done by using "webman_HTML_printer" component-type module. For that purpose, add new reference to "About" link node as below (do make sure that the "content_main" which is the "Dynamic Content ID" under "Name" sub-category is selected). Inside the main view-template, we want to use content_main DYNAMIC_CONTENT template-element as content placeholder for the welcome message.

 

After clicking the "Add" button, "webman_HTML_printer" component-type module should now has become a DYNAMIC_MODULE type reference to the "About" node as follows.

 

Write the welcome message by setting the "html_content" parameter name for "webman_HTML_printer" DYNAMIC_MODULE type reference as below.

 

Click "Set" button to apply the above parameter setting.

 

Refresh browser window/tab for mygb application again and the "About" node should now by default is selected with the welcome message generated by "webman_HTML_printer" component-type module displayed at the main content part of the main view-template.

 

Click the "Link Tree" main link of the ADT to view the current update of the overall link structure of mygb application.

 

As shown above the "Home" node has been assigned with two link references and "About" node with only one reference with the total number of link references are displayed just after the node's name. For each link references under each nodes the total number of parameter name being set are also displayed. Clicking both types of total numbers displayed will quickly bring you back to the "Link Structure/Reference" page section of the ADT.

The most important concept to be understood from the above link structure is how application main-controller (mygb.pm) will process the current active link path at the application runtime. As explained previously, when user make access to the application without link ID was supplied, "About" node that is child of "Home" node will be by default selected since both "Home" and "About" were set as auto selected nodes. In this example scenario, the current active link path will be as follows:

  1 Root ----------> Home -------------------> About         
  2                    |                         |           
  3           ---------------------      ------------------- 
  4          |     webman_main     |    |webman_HTML_printer|
  5          | webman_dyanmic_links|     ------------------- 
  6           ---------------------                          

Starting from the Root virtual node, the main-controller will trace the sequence of visible nodes and their references that build-up the current active link path. The main view-template to be assigned to the main-controller is determined by "template_default" parameter name setting made via "webman_main" MAIN_CONTROLLER type reference. If there are more than single MAIN_CONTROLLER type references are applied along the node sequence, for identical parameter name settings that have been made, the last one will overrides all other previous settings.

For DYNAMIC_MODULE type references such as "webman_dynamic_links" and "webman_HTML_printer" above, for each modules involved, the main-controller will dynamically instantiate them and applied instance's parameter settings based on module's parameter settings made via node's reference parameter settings. At the final stage, the main-controller push the returned content into main view content placeholder (DYNAMIC_CONTENT template-element) that associated with the current processed module via node's DYNAMIC_MODULE type reference. All these are done on each modules sequentially following DYNAMIC_CONTENT template-element layout order inside the main view-template file used.