1CalendarMonthSimple(3)User Contributed Perl DocumentationCalendarMonthSimple(3)
2
6 HTML::CalendarMonthSimple - Perl Module for Generating HTML Calendars
7
9 use HTML::CalendarMonthSimple;
10 $cal = new HTML::CalendarMonthSimple('year'=>2001,'month'=>2);
11 $cal->width('50%');
12 $cal->border(10);
13 $cal->header('Text at the top of the Grid');
14 $cal->setcontent(14,"Valentine's Day");
15 $cal->setdatehref(14, 'http://localhost/');
16 $cal->addcontent(14,"<p>Don't forget to buy flowers.");
17 $cal->addcontent(13,"Guess what's tomorrow?");
18 $cal->bgcolor('pink');
19 print $cal->as_HTML;
20
22 HTML::CalendarMonthSimple is a Perl module for generating,
23 manipulating, and printing a HTML calendar grid for a specified month.
24 It is intended as a faster and easier-to-use alternative to
25 HTML::CalendarMonth.
26 This module requires the Date::Calc module, which is available from
28 CPAN if you don't already have it.
29
32 Naturally, new() returns a newly constructed calendar object.
33 The optional constructor arguments 'year' and 'month' can specify which
35 month's calendar will be used. If either is omitted, the current value
36 (e.g. "today") is used. An important note is that the month and the
37 year are NOT the standard C or Perl -- use a month in the range 1-12
38 and a real year, e.g. 2001.
39 The arguments 'today_year', 'today_month', and 'today_date' may also be
41 specified, to specify what "today" is. If not specified, the system
42 clock will be used. This is particularly useful when the todaycolor()
43 et al methods are used, and/or if you're dealing with multiple
44 timezones. Note that these arguments change what "today" is, which
45 means that if you specify a today_year and a today_month then you are
46 effectively specifying a 'year' and 'month' argument as well, though
47 you can also specify a year and month argument and override the "today"
48 behavior.
49 # Examples:
51 # Create a calendar for this month.
52 $cal = new HTML::CalendarMonthSimple();
53 # A calendar for a specific month/year
54 $cal = new HTML::CalendarMonthSimple('month'=>2,'year'=>2000);
55 # Pretend that today is June 10, 2000 and display the "current" calendar
56 $cal = new HTML::CalendarMonthSimple('today_year'=>2000,'today_month'=>6,'today_date'=>10);
57
64 These methods simply return the year/month/date of the calendar, as
65 specified in the constructor.
66 monthname() returns the text name of the month, e.g. "December".
68
72 These methods are used to control the content of date cells within the
73 calendar grid. The DATE argument may be a numeric date or it may be a
74 string describing a certain occurrence of a weekday, e.g. "3MONDAY" to
75 represent "the third Monday of the month being worked with", or it may
76 be the plural of a weekday name, e.g. "wednesdays" to represent all
77 occurrences of the given weekday. The weekdays are case-insensitive.
78 Since plural weekdays (e.g. 'wednesdays') is not a single date,
80 getcontent() will return the content only for the first occurrence of
81 that day within a month.
82 # Examples:
84 # The cell for the 15th of the month will now say something.
85 $cal->setcontent(15,"An Important Event!");
86 # Later down the program, we want the content to be boldfaced.
87 $cal->setcontent(15,"<b>" . $cal->getcontent(15) . "</b>");
88 # addcontent() does not clobber existing content.
90 # Also, if you setcontent() to '', you've deleted the content.
91 $cal->setcontent(16,'');
92 $cal->addcontent(16,"<p>Hello World</p>");
93 $cal->addcontent(16,"<p>Hello Again</p>");
94 print $cal->getcontent(16); # Prints 2 sentences
95 # Padded and decimal numbers may be used, as well:
97 $cal->setcontent(3.14159,'Third of the month');
98 $cal->addcontent('00003.0000','Still the third');
99 $cal->getcontent('3'); # Gets the 2 sentences
100 # The second Sunday of May is some holiday or another...
102 $cal->addcontent('2sunday','Some Special Day') if ($cal->month() == 5);
103 # Every Wednesday is special...
105 $cal->addcontent('wednesdays','Every Wednesday!');
106 # either of these will return the content for the 1st Friday of the month
108 $cal->getcontent('1friday');
109 $cal->getcontent('Fridays'); # you really should use '1friday' for the first Friday
110 Note: A change in 1.21 is that all content is now stored in a single
112 set of date-indexed buckets. Previously, the content for weekdays,
113 plural weekdays, and numeric dates were stored separately and could be
114 fetched and set independently. This led to buggy behavior, so now a
115 single storage set is used.
116 # Example:
118 # if the 9th of the month is the second Wednesday...
119 $cal->setcontent(9,'ninth');
120 $cal->addcontent('2wednesday','second wednesday');
121 $cal->addcontent('wednesdays','every wednesday');
122 print $cal->getcontent(9);
123 In version 1.20 and previous, this would print 'ninth' but in 1.21 and
125 later, this will print all three items (since the 9th is not only the
126 9th but also a Wednesday and the second Wednesday). This could have
127 implications if you use setcontent() on a set of days, since other
128 content may be overwritten:
129 # Example:
131 # the second setcontent() effectively overwrites the first one
132 $cal->setcontent(9,'ninth');
133 $cal->setcontent('2wednesday','second wednesday');
134 $cal->setcontent('wednesdays','every wednesday');
135 print $cal->getcontent(9); # returns 'every wednesday' because that was the last assignment!
136
138 This method returns a string containing the HTML table for the month.
139 # Example:
141 print $cal->as_HTML();
142 It's okay to continue modifying the calendar after calling as_HTML().
144 My guess is that you'd want to call as_HTML() again to print the
145 further-modified calendar, but that's your business...
146
148 By default, calendars are displayed with Sunday as the first day of the
149 week (American style). Most of the world prefers for calendars to start
150 the week on Monday. This method selects which type is used: 1 specifies
151 that the week starts on Monday, 0 specifies that the week starts on
152 Sunday (the default). If no value is given at all, the current value (1
153 or 0) is returned.
154 # Example:
156 $cal->weekstartsonmonday(1); # switch over to weeks starting on Monday
157 $cal->weekstartsonmonday(0); # switch back to the default, where weeks start on Sunday
158 # Example:
160 print "The week starts on " . ($cal->weekstartsonmonday() ? 'Sunday' : 'Monday') . "\n";
161
164 These allow the date-number in a calendar cell to become a hyperlink to
165 the specified URL. The DATE may be either a numeric date or any of the
166 weekday formats described in setcontent(), et al. If plural weekdays
167 (e.g. 'wednesdays') are used with getdatehref() the URL of the first
168 occurrence of that weekday in the month will be returned (since
169 'wednesdays' is not a single date).
170 # Example:
172 # The date number in the cell for the 15th of the month will be a link
173 # then we change our mind and delete the link by assigning a null string
174 $cal->setdatehref(15,"http://sourceforge.net/");
175 $cal->setdatehref(15,'');
176 # Example:
178 # the second Wednesday of the month goes to some website
179 $cal->setdatehref('2wednesday','http://www.second-wednesday.com/');
180 # Example:
182 # every Wednesday goes to a website
183 # note that this will effectively undo the '2wednesday' assignment we just did!
184 # if we wanted the second Wednesday to go to that special URL, we should've done that one after this!
185 $cal->setdatehref('wednesdays','http://every-wednesday.net/');
186
188 contentfontsize() sets the font size for the contents of the cell,
189 overriding the browser's default. Can be expressed as an absolute (1 ..
190 6) or relative (-3 .. +3) size.
191
193 This specifies the value of the border attribute to the <TABLE>
194 declaration for the calendar. As such, this controls the thickness of
195 the border around the calendar table. The default value is 5.
196 If a value is not specified, the current value is returned. If a value
198 is specified, the border value is changed and the new value is
199 returned.
200
202 This sets the value of the width attribute to the <TABLE> declaration
203 for the calendar. As such, this controls the horizintal width of the
204 calendar.
205 The width value can be either an integer (e.g. 600) or a percentage
207 string (e.g. "80%"). Most web browsers take an integer to be the
208 table's width in pixels and a percentage to be the table width relative
209 to the screen's width. The default width is "100%".
210 If a value is not specified, the current value is returned. If a value
212 is specified, the border value is changed and the new value is
213 returned.
214 # Examples:
216 $cal->width(600); # absolute pixel width
217 $cal->width("100%"); # percentage of screen size
218
220 If showdatenumbers() is set to 1, then the as_HTML() method will put
221 date labels in each cell (e.g. a 1 on the 1st, a 2 on the 2nd, etc.) If
222 set to 0, then the date labels will not be printed. The default is 1.
223 If no value is specified, the current value is returned.
225 The date numbers are shown in boldface, normal size font. If you want
227 to change this, consider setting showdatenumbers() to 0 and using
228 setcontent()/addcontent() instead.
229
232 If showweekdayheaders() is set to 1 (the default) then calendars
233 rendered via as_HTML() will display the names of the days of the week.
234 If set to 0, the days' names will not be displayed.
235 If weekdayheadersbig() is set to 1 (the default) then the weekday
237 headers will be in <th> cells. The effect in most web browsers is that
238 they will be boldfaced and centered. If set to 0, the weekday headers
239 will be in <td> cells and in normal text.
240 For both functions, if no value is specified, the current value is
242 returned.
243
246 cellalignment() sets the value of the align attribute to the <TD> tag
247 for each day's cell. This controls how text will be horizontally
248 centered/aligned within the cells. vcellalignment() does the same for
249 vertical alignment. By default, content is aligned horizontally "left"
250 and vertically "top"
251 Any value can be used, if you think the web browser will find it
253 interesting. Some useful alignments are: left, right, center, top, and
254 bottom.
255
257 By default, the current month and year are displayed at the top of the
258 calendar grid. This is called the "header".
259 The header() method allows you to set the header to whatever you like.
261 If no new header is specified, the current header is returned.
262 If the header is set to an empty string, then no header will be printed
264 at all. (No, you won't be stuck with a big empty cell!)
265 # Example:
267 # Set the month/year header to something snazzy.
268 my($y,$m) = ( $cal->year() , $cal->monthname() );
269 $cal->header("<center><font size=+2 color=red>$m $y</font></center>\n\n");
270
289 These define the colors of the cells. If a string (which should be
290 either a HTML color-code like '#000000' or a color-word like 'yellow')
291 is supplied as an argument, then the color is set to that specified.
292 Otherwise, the current value is returned. To un-set a value, try
293 assigning the null string as a value.
294 The bgcolor defines the color of all cells. The weekdaycolor overrides
296 the bgcolor for weekdays (Monday through Friday), the weekendcolor
297 overrides the bgcolor for weekend days (Saturday and Sunday), and the
298 todaycolor overrides the bgcolor for today's date. (Which may not mean
299 a lot if you're looking at a calendar other than the current month.)
300 The weekdayheadercolor overrides the bgcolor for the weekday headers
302 that appear at the top of the calendar if showweekdayheaders() is true,
303 and weekendheadercolor does the same thing for the weekend headers. The
304 headercolor overrides the bgcolor for the month/year header at the top
305 of the calendar. The headercontentcolor(), weekdayheadercontentcolor(),
306 and weekendheadercontentcolor() methods affect the color of the
307 corresponding headers' contents and default to the contentcolor().
308 The colors of the cell borders may be set: bordercolor determines the
310 color of the calendar grid's outside border, and is the default color
311 of the inner border for individual cells. The inner bordercolor may be
312 overridden for the various types of cells via weekdaybordercolor,
313 weekendbordercolor, and todaybordercolor.
314 Finally, the color of the cells' contents may be set with contentcolor,
316 weekdaycontentcolor, weekendcontentcolor, and todaycontentcolor. The
317 contentcolor is the default color of cell content, and the other
318 methods override this for the appropriate days' cells.
319 # Example:
321 $cal->bgcolor('white'); # Set the default cell bgcolor
322 $cal->bordercolor('green'); # Set the default border color
323 $cal->contentcolor('black'); # Set the default content color
324 $cal->headercolor('yellow'); # Set the bgcolor of the Month+Year header
325 $cal->headercontentcolor('yellow'); # Set the content color of the Month+Year header
326 $cal->weekdayheadercolor('orange'); # Set the bgcolor of weekdays' headers
327 $cal->weekendheadercontentcolor('blue'); # Set the color of weekday headers' contents
328 $cal->weekendheadercolor('pink'); # Set the bgcolor of weekends' headers
329 $cal->weekdayheadercontentcolor('blue'); # Set the color of weekend headers' contents
330 $cal->weekendcolor('palegreen'); # Override weekends' cell bgcolor
331 $cal->weekendcontentcolor('blue'); # Override weekends' content color
332 $cal->todaycolor('red'); # Override today's cell bgcolor
333 $cal->todaycontentcolor('yellow'); # Override today's content color
334 print $cal->as_HTML; # Print a really ugly calendar!
335
339 These methods set the cell color and the content color for the
340 specified date, and will return the current value if STRING is not
341 specified. These color settings will override any of the settings
342 mentioned above, even todaycolor() and todaycontentcolor().
343 The date may be a numeric date or a weekday string as described in
345 setcontent() et al. Note that if a plural weekday is used (e.g.
346 'sundays') then, since it's not a single date, the value for the first
347 occurrence of that weekday will be returned (e.g. the first Sunday's
348 color).
349 # Example: a red-letter day!
351 $cal->datecolor(3,'pink');
352 $cal->datecontentcolor(3,'red');
353 # Example:
355 # Every Tuesday is a Soylent Green day...
356 # Note that if the 3rd was a Tuesday, this later assignment would override the previous one.
357 # see the docs for setcontent() et all for more information.
358 $cal->datecolor('tuesdays','green');
359 $cal->datecontentcolor('tuesdays','yellow');
360
362 If set to 1, then calendar cells will have the NOWRAP attribute set,
363 preventing their content from wrapping. If set to 0 (the default) then
364 NOWRAP is not used and very long content may cause cells to become
365 stretched out.
366
368 If set to 1, this gives very crisp edges between the table cells. If
369 set to 0 (the default) standard HTML cells are used. If neither value
370 is specified, the current value is returned.
371 FYI: To accomplish the crisp border, the entire calendar table is
373 wrapped inside a table cell.
374
376 This specifies the height in pixels of each cell in the calendar. By
377 default, no height is defined and the web browser usually chooses a
378 reasonable default.
379 If no value is given, the current value is returned.
381 To un-specify a height, try specifying a height of 0 or undef.
383
391 These specify which CSS class will be attributed to the calendar's
392 table and the calendar's cells. By default, no classes are specified or
393 used.
394 tableclass() sets the CSS class for the calendar table.
396 cellclass() is used for all calendar cells. weekdaycellclass(),
398 weekendcellclass(), and todaycellclass() override the cellclass() for
399 the corresponding types of cells. headerclass() is used for the
400 calendar's header.
401 datecellclass() sets the CSS class for the cell for the specified date.
403 This setting will override any of the other cell class settings, even
404 todaycellclass() This date must be numeric; it cannot be a string such
405 as "2wednesday"
406 If no value is given, the current value is returned.
408 To un-specify a class, try specifying an empty string, e.g.
410 cellclass('')
411
415 These functions allow the days of the week to be "renamed", which is
416 useful for displaying the weekday headers in another language.
417 # show the days of the week in Spanish
419 $cal->saturday('Sábado');
420 $cal->sunday('Domingo');
421 $cal->weekdays('Lunes','Martes','Miércoles','Jueves','Viernes');
422 # show the days of the week in German
424 $cal->saturday('Samstag');
425 $cal->sunday('Sonntag');
426 $cal->weekdays('Montag','Dienstag','Mittwoch','Donnerstag','Freitag');
427 If no value is specified (or, for weekdays() if exactly 5 arguments
429 aren't given) then the current value is returned.
430
432 Changes in 1.01: Added VALIGN to cells, to make alignment work with
433 browsers better. Added showweekdayheaders(). Corrected a bug that
434 results in the month not fitting on the grid (e.g. March 2003). Added
435 getdatehref() and setdatehref(). Corrected a bug that causes a blank
436 week to be printed at the beginning of some months.
437 Changes in 1.02: Added the color methods.
439 Changes in 1.03: More color methods!
441 Changes in 1.04: Added the "which weekday" capability to addcontent(),
443 setcontent(), and getcontent()
444 Changes in 1.05: addcontent(), et al can now take strings such as '06'
446 or decimals such as '3.14' and will handle them correctly.
447 Changes in 1.06: Changed the "which weekday" interface a bit;
449 truncations such as "2Tue" no longer work, and must be spelled out
450 entirely ("2Tuesday"). Added "plural weekdays" support (e.g.
451 "wednesdays" for "every wednesday").
452 Changes in 1.07: Fixed a typo that caused an entirely empty calendar to
454 be displayed very small.
455 Changes in 1.08: Re-did the bugfixes described in 1.05, handling padded
457 and non-integer dates.
458 Changes in 1.09: Fixed the "2Monday", et al support; a bug was found by
460 Dale Wellman <dwellman@bpnetworks.com> where the 7th, 14th, 21st, and
461 28th days weren't properly computing which Nth weekday they were so
462 "1Monday" wouldn't work if the first Monday was the 7th of the month.
463 Changes in 1.10: Added the headercontentcolor(),
465 weekendheadercontentcolor(), and weekdayheadercontentcolor() methods,
466 and made content headers use bgcolors, etc properly.
467 Changes in 1.11: The module's VERSION is now properly specified, so
469 "use" statements won't barf if they specify a minimum version. Added
470 the vcellalignment() method so vertical content alignment is
471 independent of horizontal alignment.
472 Changes in 1.12: Fixed lots of warnings that were generated if -w was
474 used, due to many values defaulting to undef/blank. Added the
475 sharpborders(), nowrap(), cellheight(), cellclass(), and
476 weekdayheadersbig() methods. cellclass(), the beginning of CSS support.
477 Thanks, Bray!
478 Changes in 1.13: Added more CSS methods: headerclass(),
480 weekdaycellclass(), weekndcellclass(), todaycellclass(). Added a test
481 to the module distribution at the urging of CPAN testers.
482 Changes in 1.14: Added the contentfontsize() method.
484 Changes in 1.15: Added the datecolor(), datecontentcolor(),
486 datebordercolor(), and datecellclass() methods, allowind cosmetic
487 attributes to be changed on a per-date basis.
488 Changes in 1.16: Fixed a very stupid bug that made addcontent() and
490 setcontent() not work. Sorry!
491 Changes in 1.17: Corrected -w warnings about uninitialized values in
493 as_HTML().
494 Changes in 1.18: Added methods: tableclass(), sunday(), saturday(),
496 weekdays(). Now day names can be internationalized!
497 Changes in 1.19: Fixed as_HTML() such that blank/0 values can be used
499 for various values, e.g. border size, colors, etc. Previously, values
500 had to be non-zero or they were assumed to be undefined.
501 Ver 1.20 was a mistake on my part and was immediately superseded by
503 1.21.
504 Changes in 1.21: Fixed the internals of setcontent() et al (see the
506 method's doc for details). Made getdatehref(), setdatehref(), and
507 datecolor() et al, able to handle weekdays in addition to numeric
508 dates.
509 Changes in 1.22: Added the much-desired weekstartsonmonday() method.
511 Now weeks can start on Monday and end with the weekend, instead of the
512 American style of starting on Sunday.
513 Changes in 1.23: Added today_year() et al. "Today" can now be
515 overridden in the constructor.
516 Changes in 1.24: Minor corrections to the HTML so it passes XML
518 validation. Thanks a bundle, Peter!
519 Changes in 1.25: A minor typo correction. Nothing big.
521
523 This Perl module is freeware. It may be copied, derived, used, and
524 distributed without limitation.
525 HTML::CalendarMonth was written and is copyrighted by Matthew P. Sisk
527 <sisk@mojotoad.com> and provided inspiration for the module's interface
528 and features. None of Matt Sisk's code appears herein.
529 HTML::CalendarMonthSimple was written by Gregor Mosheh
531 <stigmata@blackangel.net> Frankly, the major inspiration was the
532 difficulty and unnecessary complexity of HTML::CalendarMonth. (Laziness
533 is a virtue.)
534 This would have been extremely difficult if not for Date::Calc. Many
536 thanks to Steffen Beyer <sb@engelschall.com> for a very fine set of
537 date-related functions!
538 Dave Fuller <dffuller@yahoo.com> added the getdatehref() and
540 setdatehref() methods, and pointed out the bugs that were corrected in
541 1.01.
542 Danny J. Sohier <danny@gel.ulaval.ca> provided many of the color
544 functions.
545 Bernie Ledwick <bl@man.fwltech.com> provided base code for the today*()
547 functions, and for the handling of cell borders.
548 Justin Ainsworth <jrainswo@olemiss.edu> provided the vcellalignment()
550 concept and code.
551 Jessee Porter <porterje@us.ibm.com> provided fixes for 1.12 to correct
553 those warnings.
554 Bray Jones <bjones@vialogix.com> supplied the sharpborders(), nowrap(),
556 cellheight(), cellclass() methods.
557 Bill Turner <b@brilliantcorners.org> supplied the headerclass() method
559 and the rest of the methods added to 1.13
560 Bill Rhodes <wrhodes@27.org> provided the contentfontsize() method for
562 version 1.14
563 Alberto Simões <albie@alfarrabio.di.uminho.pt> provided the
565 tableclass() function and the saturday(), sunday(), and weekdays()
566 functions for version 1.18. Thanks, Alberto, I've been wanting this
567 since the beginning!
568 Blair Zajac <blair@orcaware.com> provided the fixes for 1.19
570 Thanks to Kurt <kurt@otown.com> for the bug report that made all the
572 new stuff in 1.21 possible.
573 Many thanks to Stefano Rodighiero <larsen@libero.it> for the code that
575 made weekstartsonmonday() possible. This was a much-requested feature
576 that will make many people happy!
577 Dan Boitnott <dboitnot@yahoo.com> provided today_year() et al in 1.23
579 Peter Venables <pvenables@rogers.com> provided the XML validation fixes
581 for 1.24
582
584 Hey! The above document had some coding errors, which are explained
585 below:
586 Around line 1171:
588 Non-ASCII character seen before =encoding in
589 '$cal->saturday('Sábado');'. Assuming UTF-8
590perl v5.32.0 2020-07-28 CalendarMonthSimple(3)