Webman-framework

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

About | Overview | Documentation

 

Documentation > Tutorial > 6.1 Guestbook entry page: Automatic code generation

6.1 Guestbook entry page: Automatic code generation

 

The framework provides predefined solutions for web application development at three main design levels that are architecture, module (class), and database. At the architecture level, the solution proposed is the separation of application resources as a collection of controllers and views. The controllers (main-controller and sub-controller) are modules realized from generic web solution specifications defined using component-based software development (CBSD) approach. Generally these controllers are known as component-type modules and their specifications are actually the solutions provided by the framework at module/class design level. Read the documentations on CGI_Component and webman_CGI_Component modules to get detailed information about these generic specifications.

At the database level the framework further specifies the generic table design to support the implementations of application main link structure and some parts of the application control logic elements. This is how the framework implements database-oriented approach in its development strategy. A real hands-on experience of using this particular approach has been described in section 2 through section 4 in this tutorial via the use of framework's web-based development support tool (ADT) to integrate application resources that involves main link structure, controllers, and views.

It's relatively simple to manually create a new components by customizing the base component-type modules. The documentation on framework's modules & APIs provides code templates for both, component-type child modules customization and their correspond view templates. Integration of new components into application link structure as a node references also become easy with the help of the ADT. However, if there are too many components involved, it can become tedious and error-prone to do all of those tasks manually. For that reason, the framework provides automatic code generation to create new components and integrate them into application link structure. Using guestbook entry page case study, the steps below demonstrate how automatic code generation facility can help developers use the framework in more productive way.

 

Inside the command prompt window, go to framework's off-line resources directory path (E:\wmbase\webman). Enter the dir command to list the content of this particular directory. The content might be listed as below.

 

Inside the E:\wmbase\webman directory path there will be a script named app_code_generator.pl. Currently, this is the only single script used to support automatic code generation inside the framework. Type and enter the command perl app_code_generator.pl to run the script. At the very beginning, the script will ask for application name, table name, and test option. Enter those required information as shown below.

 

For quite some time the script will prompt the message "Press enter to ...". Just press enter to proceed until the script ask for database item handling options as follows.

 

From the given options as shown in the command prompt window above, the option number "4" is one that suits the current problem to be solved that is to provide users a simple guestbook entry page.

After entering the required inputs, the script will later analyze the structure of the table name involved. As shown below, at this stage, the script give the options to exclude particular field names from being included as visible input elements inside the insert form page. All field names which start with "id_*" will be by default excluded. Following database design conventions, the framework assumes that these type of fields are an automatic generated primary key or foreign keys which values copied from other associated table's primary key. The wmf_date_created and wmf_time_created field names (fields number 4 and 5) are also excluded since their value are automatically generated by framework's database related modules/APIs.

 

All of the previous steps above provide the required information for the script to automatically write the component-type modules and their coressponding view templates as desired by the developers. After all related files of modules and view templates are written and saved in the appropriate directory path, the script will later integrate/deploy them into application main link structure as a node reference. Before the script ask the node where the reference could be added, below is the child links/nodes under the "Home" node that have been previously added using the ADT.

 

Inside the ADT's "Link Structure/Reference" section page above, put your attention to the "Sign Guestbook" node where the new reference is intended to be added. The node is referred by the link ID "7" and as shown below, when the script ask the link ID for code deployment, just enter the link ID for "Sign Guestbook" that is "7".

 

At the end of its runtime, the script will ask if all previous input settings applied should be saved. It's advisable to answer "y" for this option since if there is later a need to regenerate the exact same code specifications, the script can autonomously used the saved input settings without requiring manual intervention by developers.

 

At this point the script has already create the required modules and their coressponded view templates. There are actually one component-type module and two view templates have been generated as listed below:

E:\wmbase\webman\pm\apps\mygb\mygb_entry_std_insert.pm
E:\wmbase\public_html\cgi-bin\webman\mygb\mygb_entry_std_insert.html
E:\wmbase\public_html\cgi-bin\webman\mygb\mygb_entry_std_insert_confirm.html

For three files that have been generated, all are names start with the application table name involved (mygb_entry). Though the naming convention applied by the automatic code generator is not a mandatory but it's advisable to follow it even when the module and view template files are created manually. The naming convention is proposed with the intention to help developers to organize the files better by considering that for single application like mygb, all application modules will be stored inside a single directory E:\wmbase\webman\pm\apps\mygb and for the view templates they will be inside the E:\wmbase\public_html\cgi-bin\webman\mygb directory. The naming convention can help developers to differentiate each file based on the data entity and functions applied.

Besides generating new files of modules and view templates, the automatic code generator script also modifies the main-controller module of the application (E:\wmbase\webman\pm\apps\mygb\mygb.pm). Open the content of this main-controller module's file. The beginning part of the content should look like below.

  1 package mygb;                                                           
  2                                                                         
  3 use webman_main;                                                        
  4                                                                         
  5 @ISA=("webman_main");                                                   
  6                                                                         
  7 ### Include new customized application modules next to this line.       
  8                                                                         
  9 #__cust_mod__                                                           
 10                                                                         
 11 use mygb_entry_std_insert;                                              
 12                                                                         
 13 #__cust_mod__                                                           
 14                                                                         
 15 ### Don't remove the above "#__cust_mod__" comments since they are used 
 16 ### by the framework code generator to automatically add/remove modules.
 17 ...                                                                     
 18 ...                                                                     

Below is a brief descriptions of the beginning part of the above mygb.pm file content.
  • Line 1 - the Perl syntax (namespace) to associate the current file (mygb.pm) with the module named mygb.
  • Lines 3 and 5 - declare that mygb is actually a child module of webman_main module.
  • Line 11 - new line added by the automatic code generator so the main-controller (mygb module) can instantiate the new generated mygb_entry_std_insert module
  • .
Also pay attention to the comments at lines 15-16 where you might include new modules manually between the #__cust_mod__ comments but don't try to remove these particular special comments since they are used as tags by the code generator script to automatically add/remove the include module commands based on current modules available in the application.

As explained previously, the script will not only automatically generate new application resources (modules and view templates), but will also integrate/deploy them into application main link structure. How to manually integrate application link structure, modules, and view templates together has been demonstrated in the previous sections 3 and 4.

To check how the script integrate the new resources generated for guestbook entry page, go to ADT's "Link Structure/Reference" page section and view the "Update Reference" operation sub-section for "Sign Guestbook" node as shown below.

 

By default the script will apply the new reference to Dynamic Content ID (DYNAMIC_CONTENT template-element) named "content_main". However, if this default implementation doesn't fit with current main view template selected, a change can be made by clicking the "Change ID" link at the "Operation" column. As shown above, the new generated "mygb_entry_std_insert" module doesn't directly applied as DYNAMIC_MODULE type reference to the "Sign Guestbook" node. Intead, the script use "webman_component_selector", one of frameworks's standard component-type modules. This is for the purpose of flexibility since "webman_component_selector" module provides dynamic mechanism to run other modules based on particular CGI parameter value supplied at the runtime. Read the documentation on webman_component_selector module for more detailed descriptions about this particular component-type modules.

Click the link of "webman_component_selector" DYNAMIC_MODULE type reference and the setting applied will be displayed as follows.

 

The above CGI parameter and selected component pair-seeting indicates that "mygb_entry_std_insert" module will be instantiated and executed by "webman_component_selector" when the "Sign Guestbook" node is selected and at the same time the CGI parameter named "task" is not supplied or hold a null value. For a single "Sign Guestbook" node with "webman_component_selector" reference above, using single CGI parameter named "task", it's possible to conditionally execute other modules by applying several different CGI parameter value and selected component pair-seetings. This is the flexibility advantage offered when reference to other component-type module is made via "webman_component_selector" DYNAMIC_MODULE type reference.

For "mygb_entry_std_insert" reference made via "webman_component_selector" DYNAMIC_MODULE type reference, inside the "Operation" column click the "Set Param[03]" link. The list of all parameter settings for "mygb_entry_std_insert" reference that automatically added by the script will be displayed as below.

 

The above parameter settings simply tell "mygb_entry_std_insert" module the view template file to be used for insert confirmation page, table name that involved in the insert operation, and the field input element that can't be left blank by the users. No view template file for insert form page (default view template) is set since "mygb_entry_std_insert" is a component-type module and following the framework's CoC it can find and assign the default view template (mygb_entry_std_insert.html) by itself.

Do try to open the mygb_entry_std_insert.pm module's file and below is the beginning part of its content should look like.

  1 package mygb_entry_std_insert; 
  2                                
  3 use webman_db_item_insert;     
  4                                
  5 @ISA=("webman_db_item_insert");
  6                                
  7 ...                            
  8 ...                            

The new generated "mygb_entry_std_insert" module is actually a child module to "webman_db_item_insert" component-type module. Read the documentation on webman_db_item_insert module for more detailed descriptions on how to control the parameter settings of "mygb_entry_std_insert" module's reference.