Webman-framework

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

About | Overview | Documentation

 

Documentation > Modules and APIs > webman_calendar_weekly_timerow

webman_calendar_weekly_timerow

 

Description:

Component-type module that provides interactive navigation (weekly) on calendar data and facilities to detail date's content at time level.

 

Dependencies:

Webman-framework's Core Modules:

  • Calendar (Composition)
  • Table_List_Data (Composition)
  • TLD_HTML_Map (Composition)

Webman-framework's Component-type Modules:
  • CGI_Component::webman_CGI_component::webman_calendar_weekly (Inheritance)

 

1. CGI Parameters

Below are CGI parameters that provide control to and passed by webman_calendar_interactive instance at application run-time.

calendar_key_date => "yyyy-mm-dd"
calendar_ymd_selected => "yyyy-mm-dd" 
calendar_day => 1, 2, ... , 7
calendar_hms_start => "hh:mm:ss" 
calendar_hms_end => "hh:mm:ss"

Default active week selected is system's current active week. Changes on selected active week can be done by passing, any date ranges inside the intended week to the module via calendar_key_date CGI parameter. The CGI parameters calendar_ymd_selected, calendar_day, calendar_hms_start, and calendar_hms_end are used to store the picked date, day number, start-time, and end-time when the module is used as calendar's date-time information picker through customization inside customize_TLD function (read section 5, code lines 156-171 and 176-205).

 
2. View Template

Generally the template contains DYNAMIC_CONTENT template-elements, LIST template-elements, and a single standard HTML-form.

The first two DYNAMIC_CONTENT template-elements (lines 12 and 14) named cal_prev_week and cal_prev_week are used as place-holders for HTTP-GET links attribute to navigate calendar's weeks forward and backward.

The next two LIST template-elements (lines 24 and 29-38) named col_view_day and row_view_content together with the word patterns $tld_week_day_, $tld_week_date_, $tld_time_start_, $tld_time_end_, $tld_day1_content_ , ..., and $tld_day7_content_ are used as place-holders for selected week's days and date, date's time, and date-time's content. The word pattern $tld_column_style_, $tld_day1_column_style_, ..., and $tld_day7_column_style_ are used to control days/date, date's time, and date-time's content columns presentation style using CSS. The row_view_content LIST template-element will becomes the row of times set by the hour ranges using code at line 14 in section 3.

The standard HTML-form (lines 42-51) can be used by users to quickly jump to specific week by passing week's key date to the module via calendar_key_date CGI parameter (line 45). Inside the HTML-form there is also CGI template-element (line 48) with the word pattern $cgi_link_id_ as a place-holder for the value of link_id input element. This input element is used as an entity to pass the parameter named link_id (via POST-method) which is the standard CGI parameter name used to refer nodes' IDs that construct the overall application's link structure. The logic is to use again node's link-id which is used to call webman_calendar_weekly_timerow component-type module previously.

  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                                                                                                           
  7 <body>                                                                                                    
  8 <!-- start_view_ //-->                                                                                    
  9 <table border="1">                                                                                        
 10   <tr>                                                                                                    
 11     <th colspan="8" align="center">                                                                       
 12       <a href="<!-- dynamic_content_ name=cal_prev_week //-->">&lt;&lt;</a>                               
 13       | Weekly Calendar Title |                                                                           
 14       <a href="<!-- dynamic_content_ name=cal_next_week //-->">&gt;&gt;</a>                               
 15     </th>                                                                                                 
 16   </tr>                                                                                                   
 17                                                                                                           
 18   <tr>                                                                                                    
 19     <td align="center" style="background-color:#b4c0f2;">                                                 
 20     Time                                                                                                  
 21     </td>                                                                                                 
 22                                                                                                           
 23     <!-- start_list_ name=col_view_day //-->                                                              
 24     <td align="center" style="$tld_column_style_">$tld_week_day_<br />$tld_week_date_</td>                
 25     <!-- end_list_ //-->                                                                                  
 26   </tr>                                                                                                   
 27                                                                                                           
 28   <!-- start_list_ name=row_view_content //-->                                                            
 29   <tr style="$tld_row_style_">                                                                            
 30     <td valign="top" style="$tld_time_column_style_" align="center">$tld_time_start_ - $tld_time_end_</td>
 31     <td valign="top" style="$tld_day1_column_style_">$tld_day1_content_ </td>                             
 32     <td valign="top" style="$tld_day2_column_style_">$tld_day2_content_ </td>                             
 33     <td valign="top" style="$tld_day3_column_style_">$tld_day3_content_ </td>                             
 34     <td valign="top" style="$tld_day4_column_style_">$tld_day4_content_ </td>                             
 35     <td valign="top" style="$tld_day5_column_style_">$tld_day5_content_ </td>                             
 36     <td valign="top" style="$tld_day6_column_style_">$tld_day6_content_ </td>                             
 37     <td valign="top" style="$tld_day7_column_style_">$tld_day7_content_ </td>                             
 38   </tr>                                                                                                   
 39   <!-- end_list_ //-->                                                                                    
 40                                                                                                           
 41   <tr>                                                                                                    
 42     <form method="POST" action="./index.cgi">                                                             
 43     <th colspan="8" align="center">                                                                       
 44         Week's Date (yyyy-mm-dd):                                                                         
 45         <input type="text" size="10" name="calendar_key_date">                                            
 46         <input type="submit" name="button_submit" value="Go">                                             
 47         <!-- start_cgihtml_ //-->                                                                         
 48         <input type="hidden" name="link_id" value="$cgi_link_id_">                                        
 49         <!-- end_cgihtml_ //-->                                                                           
 50     </th>                                                                                                 
 51     </form>                                                                                               
 52   </tr>                                                                                                   
 53 </table>                                                                                                  
 54 <!-- end_view_ //-->                                                                                      
 55 </body>                                                                                                   
 56 </html>                                                                                                   


 
3. Instantiation and Basic Parameter Setting

The arguments $all, $odd, $even, $current, and $selected (lines 16-19) are CSS's strings code to control the presentation of HTML-table columns and rows used to arrange week's days/date/times and date-time's content. The $time_start and $time_end arguments at lines 21 is times in the format of "hh:mm:ss".

  1 my $component = new webman_calendar_weekly_timerow;                                   
  2                                                                                       
  3 $component->set_CGI($cgi);                                                            
  4 $component->set_DBI_Conn($db_conn);                                                   
  5                                                                                       
  6 #$component->set_Script_Ref_Name("index.cgi");                                        
  7 #$component->set_Template_Default("template_???.html");                               
  8                                                                                       
  9 ### If key date is ignored the default would be the the current date.                 
 10 #$component->set_Key_Date("yyyy-mm-dd");                                              
 11                                                                                       
 12 ### If ignored the default would be 8 for the $hour_start and 17 for                  
 13 ### the $hour_end.                                                                    
 14 #$component->set_Default_Hour_Range($hour_start, $hour_end);                          
 15                                                                                       
 16 #$component->set_Default_Date_Column_Style($all, $odd, $even, $current, $selected);   
 17 #$component->set_Default_Content_Column_Style($all, $odd, $even, $current, $selected);
 18 #$component->set_Default_Row_Style($all, $odd, $even, $current, $selected);           
 19 #$component->set_Default_Cell_Style($current, $selected);                             
 20                                                                                       
 21 #$component->add_Date_Time_Content("yyyy-mm-mm", $time_start, $time_end, $content);   


 
4. Component-type Generic Function Calls

$component->run_Task;
$component->process_Content;
$component->end_Task;

my $content = $component->get_Content;



 
5. Child Module for Customization

Most basic customization is to add content into specific calendar's date-time-cell, done inside the overriden run_Task hook function (line 57). Other more advanced and complex customization tasks are involving calendar's data-structure manipulations inside customize_TLD function.

Calendar's data-structure instance ($tld) passed to customize_TLD function (line 139) is actually Table_List_Data core module instance. There are four Table_List_Data instances involved. The first two instances are inherited from the base module (webman_calendar_weekly) of current base module (webman_calendar_weekly_timerow) and referenced internally by $this->{tld_col_date} and $this->{tld_col_content} scalars. Only $this->{tld_col_date} is manipulated as shown at lines 156-171. It's used to feed data to LIST template-element named col_view_day (see section 2).

The other two instances are locally from the current base module referenced internally by $this->{tld_dtrc_data} and $this->{tld_dtrc_view} scalars. Both are manipulated as shown at lines 150-152, 176-205, and 213-215. The $this->{tld_dtrc_data} is the real instance that holds the complete week's date-time information data structure before it's synchronized and mapped to $this->{tld_dtrc_view} (lines 213-215) for view purpose. Instance referenced by $this->{tld_dtrc_view} scalar is later used as data feeder to LIST template-element named row_view_content (see section 2).

To manipulate all these Table_List_Data's instances, customize_TLD function is called via run_Task hook function recalls while it was overriden (line 61). The mechanisms is actually the same chained from base module of current base module.

Read the comments included inside the skeleton code to get more detailed explanations for all possible customizations that could be made.

  1 package child_module_name;                                                                       
  2                                                                                                                    
  3 use webman_calendar_weekly_timerow;                                                                                
  4                                                                                                                    
  5 @ISA=("webman_calendar_weekly_timerow");                                                                           
  6                                                                                                                    
  7 sub new {                                                                                                          
  8     my $class = shift;                                                                                             
  9                                                                                                                    
 10     my $this = $class->SUPER::new();                                                                               
 11                                                                                                                    
 12     #$this->set_Debug_Mode(1, 1);                                                                                  
 13                                                                                                                    
 14     bless $this, $class;                                                                                           
 15                                                                                                                    
 16     return $this;                                                                                                  
 17 }                                                                                                                  
 18                                                                                                                    
 19 sub get_Name {                                                                                                     
 20     my $this = shift @_;                                                                                           
 21                                                                                                                    
 22     return __PACKAGE__;                                                                                            
 23 }                                                                                                                  
 24                                                                                                                    
 25 sub get_Name_Full {                                                                                                
 26     my $this = shift @_;                                                                                           
 27                                                                                                                    
 28     return $this->SUPER::get_Name_Full . "::" . __PACKAGE__;                                                       
 29 }                                                                                                                  
 30                                                                                                                    
 31 sub run_Task {                                                                                                     
 32     my $this = shift @_;                                                                                           
 33                                                                                                                    
 34     my $cgi = $this->get_CGI;                                                                                      
 35     my $dbu = $this->get_DBU;                                                                                      
 36     my $db_conn = $this->get_DB_Conn;                                                                              
 37                                                                                                                    
 38     my $login_name = $this->get_User_Login;                                                                        
 39     my @groups = $this->get_User_Groups;                                                                           
 40                                                                                                                    
 41     my $match_group = $this->match_Group($group_name_, @groups);                                                   
 42                                                                                                                    
 43     #$this->set_Key_Date("yyyy-mm-dd");                                                                            
 44                                                                                                                    
 45     #$this->set_Default_Hour_Range("hour_start_", "hour_end_");                                                    
 46                                                                                                                    
 47     ### The CSS code $selected effect the implementation at lines 156-171.                                         
 48     #$this->set_Default_Date_Column_Style($all, $odd, $even, $current, $selected);                                 
 49     #$this->set_Default_Content_Column_Style($all, $odd, $even, $current, $selected);                              
 50     #$this->set_Default_Row_Style($all, $odd, $even, $current, $selected);                                         
 51     #$this->set_Default_Cell_Style($current, $selected);                                                           
 52                                                                                                                    
 53     ### Adding content to particular date and time ranges must be done before                                      
 54     ### $this->generate_DTRC_TLD is called by $this->SUPER::run_Task().                                            
 55     #$this->add_Date_Time_Content("yyyy-mm-mm", $time_start, $time_end, $content);                                 
 56                                                                                                                    
 57     ### Recalls run_Task from parent and grandparent modules will generate $this->{tld_col_data},                  
 58     ### $this->{tld_col_content}, $this->{tld_dtrc_data}, and $this->{tld_dtrc_view} references.                   
 59     $this->SUPER::run_Task();                                                                                      
 60                                                                                                                    
 61     ### Enable the next two lines to really know how the instances                                                 
 62     ### $this->{tld_col_date} & $this->{tld_col_content} are look like.                                            
 63     #$cgi->add_Debug_Text($this->{tld_col_date}->get_Table_List, __FILE__, __LINE__);                              
 64     #$cgi->add_Debug_Text($this->{tld_col_content}->get_Table_List, __FILE__, __LINE__);                           
 65                                                                                                                    
 66     ### Enable the next two lines to really know how the instances                                                 
 67     ### $this->{tld_dtrc_data} & $this->{tld_dtrc_view} are look like.                                             
 68     #$cgi->add_Debug_Text($this->{tld_dtrc_data}->get_Table_List, __FILE__, __LINE__);                             
 69     #$cgi->add_Debug_Text($this->{tld_dtrc_view}->get_Table_List, __FILE__, __LINE__);                             
 70 }                                                                                                                  
 71                                                                                                                    
 72 sub process_Content {                                                                                              
 73     $this = shift @_;                                                                                              
 74                                                                                                                    
 75     my $cgi = $this->get_CGI;                                                                                      
 76     my $dbu = $this->get_DBU;                                                                                      
 77     my $db_conn = $this->get_DB_Conn;                                                                              
 78                                                                                                                    
 79     $this->set_Template_File($this->{template_default});                                                           
 80                                                                                                                    
 81     #print "\$this->{template_default} = " . $this->{template_default} . "<br>";                                   
 82                                                                                                                    
 83     $this->SUPER::process_Content;                                                                                 
 84 }                                                                                                                  
 85                                                                                                                    
 86 sub process_so_type_ { ### so_type_ can be: VIEW, DYNAMIC, LIST, MENU, DBHTML, SELECT, DATAHTML                    
 87     my $this = shift @_;                                                                                           
 88     my $te = shift @_;                                                                                             
 89                                                                                                                    
 90     my $cgi = $this->get_CGI;                                                                                      
 91     my $dbu = $this->get_DBU;                                                                                      
 92     my $db_conn = $this->get_DB_Conn;                                                                              
 93                                                                                                                    
 94     my $login_name = $this->get_User_Login;                                                                        
 95     my @groups = $this->get_User_Groups;                                                                           
 96                                                                                                                    
 97     my $match_group = $this->match_Group($group_name_, @groups);                                                   
 98                                                                                                                    
 99     my $te_content = $te->get_Content;                                                                             
100     my $te_type_num = $te->get_Type_Num;                                                                           
101     my $te_type_name = $te->get_Name;                                                                              
102                                                                                                                    
103     $this->add_Content($te_content);                                                                               
104                                                                                                                    
105     #if ($this->get_Error eq "") {                                                                                 
106     #   $this->add_Content($te_content);                                                                           
107                                                                                                                    
108     #} else {                                                                                                      
109     #   $this->add_Content($this->get_Error);                                                                      
110     #}                                                                                                             
111 }                                                                                                                  
112                                                                                                                    
113 ### The next function will be mainly used to customize three types of table                                        
114 ### list data (TLD) instances' sructure which are $this->{tld_col_date},                                           
115 ### $this->{tld_dtrc_data}, and $this->{tld_dtrc_view}. The instance                                               
116 ### $this->{tld_dtrc_data} has its basic columns values copied from                                                
117 ### $this->{tld_col_content}. The instances $this->{tld_col_date} and                                              
118 ### $this->{tld_col_content} have five identical column names which                                                
119 ### are 'column_style', 'current_date', 'week_day', 'week_date' and 'date_iso'.                                    
120 ### The instance $this->{tld_col_content} has one extra column which is                                            
121 ### 'week_date_content' and will not involved in the customization since it                                        
122 ### only be used as a basic data feeder to $this->{tld_dtrc_data} instance.                                        
123 ### Next is the columns names exist inside $this->{tld_dtrc_data} and                                              
124 ### $this->{tld_dtrc_view} TLD's instances                                                                         
125 ###                                                                                                                
126 ### $this->{tld_dtrc_data}: 'column_style', 'current_date', 'current_time',                                        
127 ###                         'week_day', 'week_date', 'week_date_time_content',                                     
128 ###                         'date_iso', 'time_start', and 'time_end'                                               
129 ###                                                                                                                
130 ### $this->{tld_dtrc_view}: 'row_style', 'current_time', 'time_start',                                             
131 ###                         'time_end', 'day1_content', ... , 'day7_content',                                      
132 ###                         'day1_column_style', ... , 'day7_column_style'                                         
133                                                                                                                    
134 sub customize_TLD {                                                                                                
135     my $this = shift @_;                                                                                           
136                                                                                                                    
137     my $tld = shift @_;                                                                                            
138                                                                                                                    
139     my $cgi = $this->get_CGI;                                                                                      
140     my $dbu = $this->get_DBU;                                                                                      
141     my $db_conn = $this->get_DB_Conn;                                                                              
142                                                                                                                    
143     my $std_get_data = $cgi->generate_GET_Data("link_id");                                                         
144                                                                                                                    
145     my $column_color = "#fbfbeb";                                                                                  
146                                                                                                                    
147     ### Add other new column inside $this->{tld_dtrc_data}.                                                        
148     if ($tld == $this->{tld_dtrc_data}) {                                                                          
149         $tld->add_Column("link");                                                                                  
150     }                                                                                                              
151                                                                                                                    
152     for (my $i = 0; $i < $tld->get_Row_Num; $i++) {                                                                
153         ### Make date columns are selectable via week_date link.                                                   
154         if ($tld eq $this->{tld_col_date}) {                                                                       
155             ### Make week_date as links to select/deselect date.                                                   
156             my $date_iso = $tld->get_Data($i, "date_iso");                                                         
157             my $link_properties = "title=\"Click to select date\"";                                                
158                                                                                                                    
159             if ($date_iso eq $cgi->param("calendar_ymd_selected")) {                                               
160                 $date_iso = "";                                                                                    
161                 $link_properties = "title=\"Click to deselect date\" style=\"color: #ff0000;\"";                   
162             }                                                                                                      
163                                                                                                                    
164             my $deselect_cell_data = "calendar_day=&calendar_hms_start=&calendar_hms_end=";                        
165                                                                                                                    
166             $tld->set_Data_Get_Link($i, "week_date",                                                               
167                                     "index.cgi?$std_get_data&calendar_ymd_selected=$date_iso&$deselect_cell_data", 
168                                     "$link_properties");                                                           
169         }                                                                                                          
170                                                                                                                    
171         ### Next possible operations on new column "link" inside                                                   
172         ### $this->{tld_dtrc_data} (use it as link to select/deselect                                              
173         ### cell on particular date & time).                                                                       
174         if ($tld == $this->{tld_dtrc_data}) {                                                                      
175             my $date_iso = $tld->get_Data($i, "date_iso");                                                         
176             my $day = $this->{calendar}->{day_num}->{$tld->get_Data($i, "week_day")};                              
177             my $time_start = $tld->get_Data($i, "time_start");                                                     
178             my $time_end = $tld->get_Data($i, "time_end");                                                         
179                                                                                                                    
180             ### Basic CGI data should be passed when intended to use module as                                     
181             ### calendar's date-time information picker.                                                           
182             my $ymd_selected = "calendar_ymd_selected=$date_iso";                                                  
183             my $day = "calendar_day=$day";                                                                         
184             my $hms_start = "calendar_hms_start=$time_start";                                                      
185             my $hms_end = "calendar_hms_end=$time_end";                                                            
186             my $link_properties = "title=\"Click to select cell\"";                                                
187                                                                                                                    
188             if ($date_iso eq $cgi->param("calendar_ymd_selected") &&                                               
189                 $time_start eq $cgi->param("calendar_hms_start") &&                                                
190                 $time_end eq $cgi->param("calendar_hms_end")) {                                                    
191                                                                                                                    
192                 #$ymd_selected = "calendar_ymd_selected=";                                                         
193                 $day = "calendar_day=";                                                                            
194                 $hms_start = "calendar_hms_start=";                                                                
195                 $hms_end = "calendar_hms_end=";                                                                    
196                 $link_properties = "title=\"Click to deselect cell\"";                                             
197             }                                                                                                      
198                                                                                                                    
199             $tld->set_Data($i, "link", "Link to...?");                                                             
200             $tld->set_Data_Get_Link($i, "link",                                                                    
201                                     "index.cgi?$std_get_data&$ymd_selected&$day&$hms_start&$hms_end",              
202                                     "$link_properties");                                                           
203         }                                                                                                          
204     }                                                                                                              
205                                                                                                                    
206     ### Synchronize $this->{tld_dtrc_view} with $this->{tld_dtrc_data}                                             
207     ### to support view of new column added to $this->{tld_dtrc_data}.                                             
208     ### The instance $this->{tld_dtrc_view} will have new columns named                                            
209     ### 'link1', ... , 'link7' with columns' data are mapped from the                                              
210     ### 'link' column set inside $this->{tld_dtrc_data}.                                                           
211     if ($tld == $this->{tld_dtrc_view}) {                                                                          
212         $this->synchronize_Data_View("link");                                                                      
213     }                                                                                                              
214                                                                                                                    
215     #$cgi->add_Debug_Text($tld->get_Table_List, __FILE__, __LINE__);                                               
216                                                                                                                    
217     return $tld;                                                                                                   
218 }                                                                                                                  
219                                                                                                                    
220 1;