1HTML::CalendarMonthSimpUlsee(r3)Contributed Perl DocumenHtTaMtLi:o:nCalendarMonthSimple(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 Note: This package is no longer being maintained by Gregor Mosheh
23 <stigmata@blackangel.net>. It is recommended that new development be
24 built against HTML::CalendarMonth.
25 HTML::CalendarMonthSimple is a Perl module for generating,
27 manipulating, and printing a HTML calendar grid for a specified month.
28 It is intended as a faster and easier-to-use alternative to
29 HTML::CalendarMonth.
30 This module requires the Date::Calc module, which is available from
32 CPAN if you don't already have it.
33
35 new(ARGUMENTS)
36 Naturally, new() returns a newly constructed calendar object.
37 The optional constructor arguments 'year' and 'month' can specify which
39 month's calendar will be used. If either is omitted, the current value
40 (e.g. "today") is used. An important note is that the month and the
41 year are NOT the standard C or Perl -- use a month in the range 1-12
42 and a real year, e.g. 2001.
43 The arguments 'today_year', 'today_month', and 'today_date' may also be
45 specified, to specify what "today" is. If not specified, the system
46 clock will be used. This is particularly useful when the todaycolor()
47 et al methods are used, and/or if you're dealing with multiple
48 timezones. Note that these arguments change what "today" is, which
49 means that if you specify a today_year and a today_month then you are
50 effectively specifying a 'year' and 'month' argument as well, though
51 you can also specify a year and month argument and override the "today"
52 behavior.
53 # Examples:
55 # Create a calendar for this month.
56 $cal = new HTML::CalendarMonthSimple();
57 # A calendar for a specific month/year
58 $cal = new HTML::CalendarMonthSimple('month'=>2,'year'=>2000);
59 # Pretend that today is June 10, 2000 and display the "current" calendar
60 $cal = new HTML::CalendarMonthSimple('today_year'=>2000,'today_month'=>6,'today_date'=>10);
61 year
63 month
64 today_year
65 today_month
66 today_date
67 monthname
68 These methods simply return the year/month/date of the calendar, as
69 specified in the constructor.
70 monthname() returns the text name of the month, e.g. "December".
72 setcontent(DATE,STRING)
74 addcontent(DATE,STRING)
75 highlight (@DATE)
76 Highlights the particular dates given.
77 $cal->highlight(1,10,22);
79 getcontent(DATE)
81 These methods are used to control the content of date cells within the
82 calendar grid. The DATE argument may be a numeric date or it may be a
83 string describing a certain occurrence of a weekday, e.g. "3MONDAY" to
84 represent "the third Monday of the month being worked with", or it may
85 be the plural of a weekday name, e.g. "wednesdays" to represent all
86 occurrences of the given weekday. The weekdays are case-insensitive.
87 Since plural weekdays (e.g. 'wednesdays') is not a single date,
89 getcontent() will return the content only for the first occurrence of
90 that day within a month.
91 # Examples:
93 # The cell for the 15th of the month will now say something.
94 $cal->setcontent(15,"An Important Event!");
95 # Later down the program, we want the content to be boldfaced.
96 $cal->setcontent(15,"<b>" . $cal->getcontent(15) . "</b>");
97 # addcontent() does not clobber existing content.
99 # Also, if you setcontent() to '', you've deleted the content.
100 $cal->setcontent(16,'');
101 $cal->addcontent(16,"<p>Hello World</p>");
102 $cal->addcontent(16,"<p>Hello Again</p>");
103 print $cal->getcontent(16); # Prints 2 sentences
104 # Padded and decimal numbers may be used, as well:
106 $cal->setcontent(3.14159,'Third of the month');
107 $cal->addcontent('00003.0000','Still the third');
108 $cal->getcontent('3'); # Gets the 2 sentences
109 # The second Sunday of May is some holiday or another...
111 $cal->addcontent('2sunday','Some Special Day') if ($cal->month() == 5);
112 # Every Wednesday is special...
114 $cal->addcontent('wednesdays','Every Wednesday!');
115 # either of these will return the content for the 1st Friday of the month
117 $cal->getcontent('1friday');
118 $cal->getcontent('Fridays'); # you really should use '1friday' for the first Friday
119 Note: A change in 1.21 is that all content is now stored in a single
121 set of date-indexed buckets. Previously, the content for weekdays,
122 plural weekdays, and numeric dates were stored separately and could be
123 fetched and set independently. This led to buggy behavior, so now a
124 single storage set is used.
125 # Example:
127 # if the 9th of the month is the second Wednesday...
128 $cal->setcontent(9,'ninth');
129 $cal->addcontent('2wednesday','second wednesday');
130 $cal->addcontent('wednesdays','every wednesday');
131 print $cal->getcontent(9);
132 In version 1.20 and previous, this would print 'ninth' but in 1.21 and
134 later, this will print all three items (since the 9th is not only the
135 9th but also a Wednesday and the second Wednesday). This could have
136 implications if you use setcontent() on a set of days, since other
137 content may be overwritten:
138 # Example:
140 # the second setcontent() effectively overwrites the first one
141 $cal->setcontent(9,'ninth');
142 $cal->setcontent('2wednesday','second wednesday');
143 $cal->setcontent('wednesdays','every wednesday');
144 print $cal->getcontent(9); # returns 'every wednesday' because that was the last assignment!
145 as_HTML
147 This method returns a string containing the HTML table for the month.
148 # Example:
150 print $cal->as_HTML();
151 It's okay to continue modifying the calendar after calling as_HTML().
153 My guess is that you'd want to call as_HTML() again to print the
154 further-modified calendar, but that's your business...
155 weekstartsonmonday([1|0])
157 By default, calendars are displayed with Sunday as the first day of the
158 week (American style). Most of the world prefers for calendars to start
159 the week on Monday. This method selects which type is used: 1 specifies
160 that the week starts on Monday, 0 specifies that the week starts on
161 Sunday (the default). If no value is given at all, the current value (1
162 or 0) is returned.
163 # Example:
165 $cal->weekstartsonmonday(1); # switch over to weeks starting on Monday
166 $cal->weekstartsonmonday(0); # switch back to the default, where weeks start on Sunday
167 # Example:
169 print "The week starts on " . ($cal->weekstartsonmonday() ? 'Sunday' : 'Monday') . "\n";
170 Days_in_Month
172 This function returns the number of days on the current calendar.
173 foreach my $day (1 .. $cal->Days_in_Month) {
175 $cal->setdatehref($day, &make_url($cal->year, $cal->month, $day));
176 }
177 setdatehref(DATE,URL_STRING)
179 getdatehref(DATE)
180 These allow the date-number in a calendar cell to become a hyperlink to
181 the specified URL. The DATE may be either a numeric date or any of the
182 weekday formats described in setcontent(), et al. If plural weekdays
183 (e.g. 'wednesdays') are used with getdatehref() the URL of the first
184 occurrence of that weekday in the month will be returned (since
185 'wednesdays' is not a single date).
186 # Example:
188 # The date number in the cell for the 15th of the month will be a link
189 # then we change our mind and delete the link by assigning a null string
190 $cal->setdatehref(15,"http://sourceforge.net/");
191 $cal->setdatehref(15,'');
192 # Example:
194 # the second Wednesday of the month goes to some website
195 $cal->setdatehref('2wednesday','http://www.second-wednesday.com/');
196 # Example:
198 # every Wednesday goes to a website
199 # note that this will effectively undo the '2wednesday' assignment we just did!
200 # if we wanted the second Wednesday to go to that special URL, we should've done that one after this!
201 $cal->setdatehref('wednesdays','http://every-wednesday.net/');
202 contentfontsize([STRING])
204 contentfontsize() sets the font size for the contents of the cell,
205 overriding the browser's default. Can be expressed as an absolute (1 ..
206 6) or relative (-3 .. +3) size.
207 border([INTEGER])
209 This specifies the value of the border attribute to the <TABLE>
210 declaration for the calendar. As such, this controls the thickness of
211 the border around the calendar table. The default value is 5.
212 If a value is not specified, the current value is returned. If a value
214 is specified, the border value is changed and the new value is
215 returned.
216 cellpadding
218 cellspacing
219 width([INTEGER][%])
220 This sets the value of the width attribute to the <TABLE> declaration
221 for the calendar. As such, this controls the horizintal width of the
222 calendar.
223 The width value can be either an integer (e.g. 600) or a percentage
225 string (e.g. "80%"). Most web browsers take an integer to be the
226 table's width in pixels and a percentage to be the table width relative
227 to the screen's width. The default width is "100%".
228 If a value is not specified, the current value is returned. If a value
230 is specified, the border value is changed and the new value is
231 returned.
232 # Examples:
234 $cal->width(600); # absolute pixel width
235 $cal->width("100%"); # percentage of screen size
236 showdatenumbers([1 or 0])
238 If showdatenumbers() is set to 1, then the as_HTML() method will put
239 date labels in each cell (e.g. a 1 on the 1st, a 2 on the 2nd, etc.) If
240 set to 0, then the date labels will not be printed. The default is 1.
241 If no value is specified, the current value is returned.
243 The date numbers are shown in boldface, normal size font. If you want
245 to change this, consider setting showdatenumbers() to 0 and using
246 setcontent()/addcontent() instead.
247 showweekdayheaders([1 or 0])
249 weekdayheadersbig([1 or 0])
250 If showweekdayheaders() is set to 1 (the default) then calendars
251 rendered via as_HTML() will display the names of the days of the week.
252 If set to 0, the days' names will not be displayed.
253 If weekdayheadersbig() is set to 1 (the default) then the weekday
255 headers will be in <th> cells. The effect in most web browsers is that
256 they will be boldfaced and centered. If set to 0, the weekday headers
257 will be in <td> cells and in normal text.
258 For both functions, if no value is specified, the current value is
260 returned.
261 cellalignment([STRING])
263 vcellalignment([STRING])
264 cellalignment() sets the value of the align attribute to the <TD> tag
265 for each day's cell. This controls how text will be horizontally
266 centered/aligned within the cells. vcellalignment() does the same for
267 vertical alignment. By default, content is aligned horizontally "left"
268 and vertically "top"
269 Any value can be used, if you think the web browser will find it
271 interesting. Some useful alignments are: left, right, center, top, and
272 bottom.
273 header([STRING])
275 By default, the current month and year are displayed at the top of the
276 calendar grid. This is called the "header".
277 The header() method allows you to set the header to whatever you like.
279 If no new header is specified, the current header is returned.
280 If the header is set to an empty string, then no header will be printed
282 at all. (No, you won't be stuck with a big empty cell!)
283 # Example:
285 # Set the month/year header to something snazzy.
286 my($y,$m) = ( $cal->year() , $cal->monthname() );
287 $cal->header("<center><font size=+2 color=red>$m $y</font></center>\n\n");
288 bgcolor([STRING])
290 weekdaycolor([STRING])
291 weekendcolor([STRING])
292 todaycolor([STRING])
293 bordercolor([STRING])
294 highlightbordercolor([STRING])
295 weekdaybordercolor([STRING])
296 weekendbordercolor([STRING])
297 todaybordercolor([STRING])
298 contentcolor([STRING])
299 highlightcontentcolor([STRING])
300 weekdaycontentcolor([STRING])
301 weekendcontentcolor([STRING])
302 todaycontentcolor([STRING])
303 headercolor([STRING])
304 headercontentcolor([STRING])
305 weekdayheadercolor([STRING])
306 weekdayheadercontentcolor([STRING])
307 weekendheadercolor([STRING])
308 weekendheadercontentcolor([STRING])
309 These define the colors of the cells. If a string (which should be
310 either a HTML color-code like '#000000' or a color-word like 'yellow')
311 is supplied as an argument, then the color is set to that specified.
312 Otherwise, the current value is returned. To un-set a value, try
313 assigning the null string as a value.
314 The bgcolor defines the color of all cells. The weekdaycolor overrides
316 the bgcolor for weekdays (Monday through Friday), the weekendcolor
317 overrides the bgcolor for weekend days (Saturday and Sunday), and the
318 todaycolor overrides the bgcolor for today's date. (Which may not mean
319 a lot if you're looking at a calendar other than the current month.)
320 The weekdayheadercolor overrides the bgcolor for the weekday headers
322 that appear at the top of the calendar if showweekdayheaders() is true,
323 and weekendheadercolor does the same thing for the weekend headers. The
324 headercolor overrides the bgcolor for the month/year header at the top
325 of the calendar. The headercontentcolor(), weekdayheadercontentcolor(),
326 and weekendheadercontentcolor() methods affect the color of the
327 corresponding headers' contents and default to the contentcolor().
328 The colors of the cell borders may be set: bordercolor determines the
330 color of the calendar grid's outside border, and is the default color
331 of the inner border for individual cells. The inner bordercolor may be
332 overridden for the various types of cells via weekdaybordercolor,
333 weekendbordercolor, and todaybordercolor.
334 Finally, the color of the cells' contents may be set with contentcolor,
336 weekdaycontentcolor, weekendcontentcolor, and todaycontentcolor. The
337 contentcolor is the default color of cell content, and the other
338 methods override this for the appropriate days' cells.
339 # Example:
341 $cal->bgcolor('white'); # Set the default cell bgcolor
342 $cal->bordercolor('green'); # Set the default border color
343 $cal->contentcolor('black'); # Set the default content color
344 $cal->headercolor('yellow'); # Set the bgcolor of the Month+Year header
345 $cal->headercontentcolor('yellow'); # Set the content color of the Month+Year header
346 $cal->weekdayheadercolor('orange'); # Set the bgcolor of weekdays' headers
347 $cal->weekendheadercontentcolor('blue'); # Set the color of weekday headers' contents
348 $cal->weekendheadercolor('pink'); # Set the bgcolor of weekends' headers
349 $cal->weekdayheadercontentcolor('blue'); # Set the color of weekend headers' contents
350 $cal->weekendcolor('palegreen'); # Override weekends' cell bgcolor
351 $cal->weekendcontentcolor('blue'); # Override weekends' content color
352 $cal->todaycolor('red'); # Override today's cell bgcolor
353 $cal->todaycontentcolor('yellow'); # Override today's content color
354 print $cal->as_HTML; # Print a really ugly calendar!
355 datecolor(DATE,[STRING])
357 datecontentcolor(DATE,[STRING])
358 datebordercolor(DATE,[STRING])
359 These methods set the cell color and the content color for the
360 specified date, and will return the current value if STRING is not
361 specified. These color settings will override any of the settings
362 mentioned above, even todaycolor() and todaycontentcolor().
363 The date may be a numeric date or a weekday string as described in
365 setcontent() et al. Note that if a plural weekday is used (e.g.
366 'sundays') then, since it's not a single date, the value for the first
367 occurrence of that weekday will be returned (e.g. the first Sunday's
368 color).
369 # Example: a red-letter day!
371 $cal->datecolor(3,'pink');
372 $cal->datecontentcolor(3,'red');
373 # Example:
375 # Every Tuesday is a Soylent Green day...
376 # Note that if the 3rd was a Tuesday, this later assignment would override the previous one.
377 # see the docs for setcontent() et all for more information.
378 $cal->datecolor('tuesdays','green');
379 $cal->datecontentcolor('tuesdays','yellow');
380 nowrap([1 or 0])
382 If set to 1, then calendar cells will have the NOWRAP attribute set,
383 preventing their content from wrapping. If set to 0 (the default) then
384 NOWRAP is not used and very long content may cause cells to become
385 stretched out.
386 sharpborders([1 or 0])
388 If set to 1, this gives very crisp edges between the table cells. If
389 set to 0 (the default) standard HTML cells are used. If neither value
390 is specified, the current value is returned.
391 FYI: To accomplish the crisp border, the entire calendar table is
393 wrapped inside a table cell.
394 cellheight([NUMBER])
396 This specifies the height in pixels of each cell in the calendar. By
397 default, no height is defined and the web browser usually chooses a
398 reasonable default.
399 If no value is given, the current value is returned.
401 To un-specify a height, try specifying a height of 0 or undef.
403 tableclass([STRING])
405 cellclass([STRING])
406 weekdaycellclass([STRING])
407 weekendcellclass([STRING])
408 todaycellclass([STRING])
409 datecellclass(DATE,[STRING])
410 headerclass([STRING])
411 These specify which CSS class will be attributed to the calendar's
412 table and the calendar's cells. By default, no classes are specified or
413 used.
414 tableclass() sets the CSS class for the calendar table.
416 cellclass() is used for all calendar cells. weekdaycellclass(),
418 weekendcellclass(), and todaycellclass() override the cellclass() for
419 the corresponding types of cells. headerclass() is used for the
420 calendar's header.
421 datecellclass() sets the CSS class for the cell for the specified date.
423 This setting will override any of the other cell class settings, even
424 todaycellclass() This date must be numeric; it cannot be a string such
425 as "2wednesday"
426 If no value is given, the current value is returned.
428 To un-specify a class, try specifying an empty string, e.g.
430 cellclass('')
431 sunday([STRING])
433 saturday([STRING])
434 weekdays([MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY])
435 These functions allow the days of the week to be "renamed", which is
436 useful for displaying the weekday headers in another language.
437 # show the days of the week in Spanish
439 $cal->saturday('Sábado');
440 $cal->sunday('Domingo');
441 $cal->weekdays('Lunes','Martes','Miércoles','Jueves','Viernes');
442 # show the days of the week in German
444 $cal->saturday('Samstag');
445 $cal->sunday('Sonntag');
446 $cal->weekdays('Montag','Dienstag','Mittwoch','Donnerstag','Freitag');
447 If no value is specified (or, for weekdays() if exactly 5 arguments
449 aren't given) then the current value is returned.
450
452 Send bug reports to the author and log on RT.
453
455 This program is free software licensed under the...
456 The BSD License
458 The full text of the license can be found in the LICENSE file included
460 with this module.
461 Note: Versions prior to 1.26 were licensed under a BSD-like statement
463 "This Perl module is freeware. It may be copied, derived, used, and
464 distributed without limitation."
465
467 HTML::CalendarMonth was written and is copyrighted by Matthew P. Sisk
468 <sisk@mojotoad.com> and provided inspiration for the module's interface
469 and features. None of Matt Sisk's code appears herein.
470 HTML::CalendarMonthSimple was written by Gregor Mosheh
472 <stigmata@blackangel.net> Frankly, the major inspiration was the
473 difficulty and unnecessary complexity of HTML::CalendarMonth. (Laziness
474 is a virtue.)
475 This would have been extremely difficult if not for Date::Calc. Many
477 thanks to Steffen Beyer <sb@engelschall.com> for a very fine set of
478 date-related functions!
479 Dave Fuller <dffuller@yahoo.com> added the getdatehref() and
481 setdatehref() methods, and pointed out the bugs that were corrected in
482 1.01.
483 Danny J. Sohier <danny@gel.ulaval.ca> provided many of the color
485 functions.
486 Bernie Ledwick <bl@man.fwltech.com> provided base code for the today*()
488 functions, and for the handling of cell borders.
489 Justin Ainsworth <jrainswo@olemiss.edu> provided the vcellalignment()
491 concept and code.
492 Jessee Porter <porterje@us.ibm.com> provided fixes for 1.12 to correct
494 those warnings.
495 Bray Jones <bjones@vialogix.com> supplied the sharpborders(), nowrap(),
497 cellheight(), cellclass() methods.
498 Bill Turner <b@brilliantcorners.org> supplied the headerclass() method
500 and the rest of the methods added to 1.13
501 Bill Rhodes <wrhodes@27.org> provided the contentfontsize() method for
503 version 1.14
504 Alberto Simões <albie@alfarrabio.di.uminho.pt> provided the
506 tableclass() function and the saturday(), sunday(), and weekdays()
507 functions for version 1.18. Thanks, Alberto, I've been wanting this
508 since the beginning!
509 Blair Zajac <blair@orcaware.com> provided the fixes for 1.19
511 Thanks to Kurt <kurt@otown.com> for the bug report that made all the
513 new stuff in 1.21 possible.
514 Many thanks to Stefano Rodighiero <larsen@libero.it> for the code that
516 made weekstartsonmonday() possible. This was a much-requested feature
517 that will make many people happy!
518 Dan Boitnott <dboitnot@yahoo.com> provided today_year() et al in 1.23
520 Peter Venables <pvenables@rogers.com> provided the XML validation fixes
522 for 1.24
523
525 Hey! The above document had some coding errors, which are explained
526 below:
527 Around line 1229:
529 Non-ASCII character seen before =encoding in
530 '$cal->saturday('Sábado');'. Assuming UTF-8
531perl v5.38.0 2023-07-20 HTML::CalendarMonthSimple(3)