1CalendarMonthSimple(3)User Contributed Perl DocumentationCalendarMonthSimple(3)
2
3
4

NAME

6       HTML::CalendarMonthSimple - Perl Module for Generating HTML Calendars
7

SYNOPSIS

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

DESCRIPTION

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
27       This module requires the Date::Calc module, which is available from
28       CPAN if you don't already have it.
29

INTERFACE METHODS

new(ARGUMENTS)

32       Naturally, new() returns a newly constructed calendar object.
33
34       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
40       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
50          # 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

year()

month()

today_year()

today_month()

today_date()

monthname()

64       These methods simply return the year/month/date of the calendar, as
65       specified in the constructor.
66
67       monthname() returns the text name of the month, e.g. "December".
68

setcontent(DATE,STRING)

addcontent(DATE,STRING)

getcontent(DATE)

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
79       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
83          # 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
89          # 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
96          # 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
101          # The second Sunday of May is some holiday or another...
102          $cal->addcontent('2sunday','Some Special Day') if ($cal->month() == 5);
103
104          # Every Wednesday is special...
105          $cal->addcontent('wednesdays','Every Wednesday!');
106
107          # 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
111       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
117          # 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
124       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
130          # 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

as_HTML()

138       This method returns a string containing the HTML table for the month.
139
140          # Example:
141          print $cal->as_HTML();
142
143       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

weekstartsonmonday([1|0])

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
155          # 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
159          # Example:
160          print "The week starts on " . ($cal->weekstartsonmonday() ? 'Sunday' : 'Monday') . "\n";
161

setdatehref(DATE,URL_STRING)

getdatehref(DATE)

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
171          # 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
177          # Example:
178          # the second Wednesday of the month goes to some website
179          $cal->setdatehref('2wednesday','http://www.second-wednesday.com/');
180
181          # 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

contentfontsize([STRING])

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

border([INTEGER])

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
197       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

width([INTEGER][%])

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
206       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
211       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
215          # Examples:
216          $cal->width(600);    # absolute pixel width
217          $cal->width("100%"); # percentage of screen size
218

showdatenumbers([1 or 0])

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
224       If no value is specified, the current value is returned.
225
226       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

showweekdayheaders([1 or 0])

weekdayheadersbig([1 or 0])

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
236       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
241       For both functions, if no value is specified, the current value is
242       returned.
243

cellalignment([STRING])

vcellalignment([STRING])

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
252       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

header([STRING])

257       By default, the current month and year are displayed at the top of the
258       calendar grid. This is called the "header".
259
260       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
263       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
266          # 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

bgcolor([STRING])

weekdaycolor([STRING])

weekendcolor([STRING])

todaycolor([STRING])

bordercolor([STRING])

weekdaybordercolor([STRING])

weekendbordercolor([STRING])

todaybordercolor([STRING])

contentcolor([STRING])

weekdaycontentcolor([STRING])

weekendcontentcolor([STRING])

todaycontentcolor([STRING])

headercolor([STRING])

headercontentcolor([STRING])

weekdayheadercolor([STRING])

weekdayheadercontentcolor([STRING])

weekendheadercolor([STRING])

weekendheadercontentcolor([STRING])

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
295       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
301       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
309       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
315       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
320          # 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

datecolor(DATE,[STRING])

datecontentcolor(DATE,[STRING])

datebordercolor(DATE,[STRING])

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
344       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
350          # Example: a red-letter day!
351          $cal->datecolor(3,'pink');
352          $cal->datecontentcolor(3,'red');
353
354          # 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

nowrap([1 or 0])

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

sharpborders([1 or 0])

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
372       FYI: To accomplish the crisp border, the entire calendar table is
373       wrapped inside a table cell.
374

cellheight([NUMBER])

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
380       If no value is given, the current value is returned.
381
382       To un-specify a height, try specifying a height of 0 or undef.
383

tableclass([STRING])

cellclass([STRING])

weekdaycellclass([STRING])

weekendcellclass([STRING])

todaycellclass([STRING])

datecellclass(DATE,[STRING])

headerclass([STRING])

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
395       tableclass() sets the CSS class for the calendar table.
396
397       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
402       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
407       If no value is given, the current value is returned.
408
409       To un-specify a class, try specifying an empty string, e.g.
410       cellclass('')
411

sunday([STRING])

saturday([STRING])

weekdays([MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY])

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
418          # 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
423          # 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
428       If no value is specified (or, for weekdays() if exactly 5 arguments
429       aren't given) then the current value is returned.
430

BUGS, TODO, CHANGES

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
438       Changes in 1.02: Added the color methods.
439
440       Changes in 1.03: More color methods!
441
442       Changes in 1.04: Added the "which weekday" capability to addcontent(),
443       setcontent(), and getcontent()
444
445       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
448       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
453       Changes in 1.07: Fixed a typo that caused an entirely empty calendar to
454       be displayed very small.
455
456       Changes in 1.08: Re-did the bugfixes described in 1.05, handling padded
457       and non-integer dates.
458
459       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
464       Changes in 1.10: Added the headercontentcolor(),
465       weekendheadercontentcolor(), and weekdayheadercontentcolor() methods,
466       and made content headers use bgcolors, etc properly.
467
468       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
473       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
479       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
483       Changes in 1.14: Added the contentfontsize() method.
484
485       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
489       Changes in 1.16: Fixed a very stupid bug that made addcontent() and
490       setcontent() not work. Sorry!
491
492       Changes in 1.17: Corrected -w warnings about uninitialized values in
493       as_HTML().
494
495       Changes in 1.18: Added methods: tableclass(), sunday(), saturday(),
496       weekdays(). Now day names can be internationalized!
497
498       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
502       Ver 1.20 was a mistake on my part and was immediately superseded by
503       1.21.
504
505       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
510       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
514       Changes in 1.23: Added today_year() et al. "Today" can now be
515       overridden in the constructor.
516
517       Changes in 1.24: Minor corrections to the HTML so it passes XML
518       validation. Thanks a bundle, Peter!
519
520       Changes in 1.25: A minor typo correction. Nothing big.
521

AUTHORS, CREDITS, COPYRIGHTS

523       This Perl module is freeware. It may be copied, derived, used, and
524       distributed without limitation.
525
526       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
530       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
535       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
539       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
543       Danny J. Sohier <danny@gel.ulaval.ca> provided many of the color
544       functions.
545
546       Bernie Ledwick <bl@man.fwltech.com> provided base code for the today*()
547       functions, and for the handling of cell borders.
548
549       Justin Ainsworth <jrainswo@olemiss.edu> provided the vcellalignment()
550       concept and code.
551
552       Jessee Porter <porterje@us.ibm.com> provided fixes for 1.12 to correct
553       those warnings.
554
555       Bray Jones <bjones@vialogix.com> supplied the sharpborders(), nowrap(),
556       cellheight(), cellclass() methods.
557
558       Bill Turner <b@brilliantcorners.org> supplied the headerclass() method
559       and the rest of the methods added to 1.13
560
561       Bill Rhodes <wrhodes@27.org> provided the contentfontsize() method for
562       version 1.14
563
564       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
569       Blair Zajac <blair@orcaware.com> provided the fixes for 1.19
570
571       Thanks to Kurt <kurt@otown.com> for the bug report that made all the
572       new stuff in 1.21 possible.
573
574       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
578       Dan Boitnott <dboitnot@yahoo.com> provided today_year() et al in 1.23
579
580       Peter Venables <pvenables@rogers.com> provided the XML validation fixes
581       for 1.24
582

POD ERRORS

584       Hey! The above document had some coding errors, which are explained
585       below:
586
587       Around line 1171:
588           Non-ASCII character seen before =encoding in
589           '$cal->saturday('Sábado');'. Assuming UTF-8
590
591
592
593perl v5.32.0                      2020-07-28            CalendarMonthSimple(3)
Impressum