HTML::...hSimple(3pm)

📦
version 1.27 · 4 versions
, in debian trixie, ubuntu resolute, ubuntu stonking

✨ HTML::CalendarMonthSimple(3pm) ✨

User Contributed Perl Documentation — yeah bestie, this is the one, the calendar-maker, the icon 💅

🌸 NAME 🌸

HTML::CalendarMonthSimple — Perl Module for Generating HTML Calendars 💖

🎀 SYNOPSIS 🎀

use HTML::CalendarMonthSimple;
$cal = new HTML::CalendarMonthSimple('year'=>2001,'month'=>2);
$cal->width('50%');
$cal->border(10);
$cal->header('Text at the top of the Grid');
$cal->setcontent(14,"Valentine's Day");
$cal->setdatehref(14, 'http://localhost/');
$cal->addcontent(14,"<p>Don't forget to buy flowers.");
$cal->addcontent(13,"Guess what's tomorrow?");
$cal->bgcolor('pink');
print $cal->as_HTML;

look at that. a whole month. rendered. periodt. ✨

🦋 DESCRIPTION 🦋

Heads up, bestie: this package is no longer being maintained by Gregor Mosheh <stigmata@blackangel.net>. If you're starting something new, the recommendation is to build against HTML::CalendarMonth instead. Fr fr, that's the official word.

HTML::CalendarMonthSimple is a Perl module for generating, manipulating, and printing an HTML calendar grid for a month you pick. It's meant to be the faster, easier-to-use alternative to HTML::CalendarMonth — like, the low-effort glow-up version. 😌

This module requires the Date::Calc module, which you can grab from CPAN if it's not already vibing on your system. 🍓

👑 INTERFACE METHODS 👑

💜 new(ARGUMENTS)

Obviously, new() hands you back a freshly constructed calendar object. Main character energy from day one. 🫶

The optional constructor arguments 'year' and 'month' tell it which month's calendar you want. If you skip either one, the current value (i.e. "today") is used instead. Important note: the month and year here are NOT the standard C or Perl style — use a month in the range 1-12 and a real year, like 2001. No zero-indexed nonsense, okay? 🙅

You can also pass 'today_year', 'today_month', and 'today_date' to specify exactly what "today" even is. If you don't specify them, the system clock gets used. This is genuinely so useful when you're using the todaycolor() et al methods, and/or when you're juggling multiple timezones. 🌍 Note that these arguments change what "today" means — so if you specify a today_year and a today_month, you're effectively specifying 'year' and 'month' too. But you can also specify a year and month argument and override the "today" behavior. Either way, you got options, bestie. 💅

# Examples:
# Create a calendar for this month.
$cal = new HTML::CalendarMonthSimple();
# A calendar for a specific month/year
$cal = new HTML::CalendarMonthSimple('month'=>2,'year'=>2000);
# Pretend that today is June 10, 2000 and display the "current" calendar
$cal = new HTML::CalendarMonthSimple('today_year'=>2000,'today_month'=>6,'today_date'=>10);

⭐ year, month, today_year, today_month, today_date, monthname

These methods just hand you back the year / month / date of the calendar, exactly as you specified it in the constructor. Simple. Clean. Iconic. ✨

monthname() returns the text name of the month, e.g. "December". 🎄

🧚 setcontent(DATE,STRING), addcontent(DATE,STRING), highlight (@DATE)

highlight() does exactly what it sounds like — it highlights the particular dates you give it. 🌈

$cal->highlight(1,10,22);

🌟 getcontent(DATE)

These methods are your controls for the content of the date cells inside the calendar grid. The DATE argument can be:

  • a numeric date, or
  • a string describing a certain occurrence of a weekday, e.g. "3MONDAY" meaning "the third Monday of the month being worked with", or
  • the plural of a weekday name, e.g. "wednesdays" meaning all occurrences of that weekday.

The weekdays are case-insensitive. 😌

Since plural weekdays (e.g. 'wednesdays') aren't a single date, getcontent() will return the content only for the first occurrence of that day within the month. iykyk.

# Examples:
# The cell for the 15th of the month will now say something.
$cal->setcontent(15,"An Important Event!");
# Later down the program, we want the content to be boldfaced.
$cal->setcontent(15,"<b>" . $cal->getcontent(15) . "</b>");

# addcontent() does not clobber existing content.
# Also, if you setcontent() to '', you've deleted the content.
$cal->setcontent(16,'');
$cal->addcontent(16,"<p>Hello World</p>");
$cal->addcontent(16,"<p>Hello Again</p>");
print $cal->getcontent(16); # Prints 2 sentences

# Padded and decimal numbers may be used, as well:
$cal->setcontent(3.14159,'Third of the month');
$cal->addcontent('00003.0000','Still the third');
$cal->getcontent('3'); # Gets the 2 sentences

# The second Sunday of May is some holiday or another...
$cal->addcontent('2sunday','Some Special Day') if ($cal->month() == 5);

# Every Wednesday is special...
$cal->addcontent('wednesdays','Every Wednesday!');

# either of these will return the content for the 1st Friday of the month
$cal->getcontent('1friday');
$cal->getcontent('Fridays'); # you really should use '1friday' for the first Friday
Note: a change in 1.21 is that all content is now stored in a single set of date-indexed buckets. Before that, the content for weekdays, plural weekdays, and numeric dates lived in separate storage and could be fetched and set independently. That caused buggy behavior, so now there's one single storage set. Growth. Maturity. We love to see it. 💅
# Example:
# if the 9th of the month is the second Wednesday...
$cal->setcontent(9,'ninth');
$cal->addcontent('2wednesday','second wednesday');
$cal->addcontent('wednesdays','every wednesday');
print $cal->getcontent(9);

In version 1.20 and previous, that would print 'ninth'. But in 1.21 and later, it prints all three items — because the 9th isn't only the 9th, it's also a Wednesday AND the second Wednesday. multitasking queen. 👑

This could have implications if you use setcontent() on a set of days, since other content may get overwritten:

# Example:
# the second setcontent() effectively overwrites the first one
$cal->setcontent(9,'ninth');
$cal->setcontent('2wednesday','second wednesday');
$cal->setcontent('wednesdays','every wednesday');
print $cal->getcontent(9); # returns 'every wednesday' because that was the last assignment!

🎀 as_HTML

This method returns a string containing the HTML table for the month. That's it. That's the whole job. 🫶

# Example:
print $cal->as_HTML();

It's totally okay to keep modifying the calendar after you call as_HTML(). My guess is you'd want to call as_HTML() again to print the further-modified calendar, but honestly, that's your business... 🙈

🌈 weekstartsonmonday([1|0])

By default, calendars display with Sunday as the first day of the week (American style). Most of the world prefers the week to start on Monday. This method picks which one you get:

  • 1 — the week starts on Monday
  • 0 — the week starts on Sunday (this is the default)

If you give no value at all, the current value (1 or 0) is returned instead. ✨

# Example:
$cal->weekstartsonmonday(1); # switch over to weeks starting on Monday
$cal->weekstartsonmonday(0); # switch back to the default, where weeks start on Sunday

# Example:
print "The week starts on " . ($cal->weekstartsonmonday() ? 'Sunday' : 'Monday') . "\n";

🦋 Days_in_Month

This function returns the number of days on the current calendar. 📆

foreach my $day (1 .. $cal->Days_in_Month) {
  $cal->setdatehref($day, &make_url($cal->year, $cal->month, $day));
}

💖 setdatehref(DATE,URL_STRING), getdatehref(DATE)

These let the date-number in a calendar cell become a hyperlink to whatever URL you want. 🔗 The DATE can be a numeric date, or any of the weekday formats described in setcontent(), et al. If you use plural weekdays (e.g. 'wednesdays') with getdatehref(), you get the URL of the first occurrence of that weekday in the month — because 'wednesdays' is not a single date, bestie. 😌

# Example:
# The date number in the cell for the 15th of the month will be a link
# then we change our mind and delete the link by assigning a null string
$cal->setdatehref(15,"http://sourceforge.net/");
$cal->setdatehref(15,'');

# Example:
# the second Wednesday of the month goes to some website
$cal->setdatehref('2wednesday','http://www.second-wednesday.com/');

# Example:
# every Wednesday goes to a website
# note that this will effectively undo the '2wednesday' assignment we just did!
# if we wanted the second Wednesday to go to that special URL, we should've done that one after this!
$cal->setdatehref('wednesdays','http://every-wednesday.net/');

🍓 contentfontsize([STRING])

contentfontsize() sets the font size for the contents of the cell, overriding the browser's default. 🎀 You can express it as an absolute size (1 .. 6) or a relative size (-3 .. +3). Pick your vibe.

🌟 border([INTEGER])

This sets the value of the border attribute on the <TABLE> declaration for the calendar. So basically, it controls how thick the border around the calendar table is. The default value is 5. 💅

  • If you don't specify a value, the current value is returned.
  • If you do specify a value, the border value gets changed and the new value is returned. two-for-one, we love efficiency. ✨

🧚 cellpadding, cellspacing, width([INTEGER][%])

This sets the value of the width attribute on the <TABLE> declaration for the calendar. So it controls the horizontal width of the calendar. 📏

The width value can be either an integer (e.g. 600) or a percentage string (e.g. "80%"). Most web browsers treat an integer as the table's width in pixels, and a percentage as the table width relative to the screen's width. The default width is "100%". 👑

  • If you don't specify a value, the current value is returned.
  • If you do specify a value, the border value gets changed and the new value is returned.
# Examples:
$cal->width(600);    # absolute pixel width
$cal->width("100%"); # percentage of screen size

🌸 showdatenumbers([1 or 0])

If showdatenumbers() is set to 1, then the as_HTML() method puts date labels in each cell (e.g. a 1 on the 1st, a 2 on the 2nd, etc.). If it's set to 0, those date labels won't be printed. The default is 1. ✨

If no value is specified, the current value is returned.

The date numbers show up in boldface, normal size font. If you want to change that, consider setting showdatenumbers() to 0 and using setcontent() / addcontent() instead. DIY era. 💅

🌈 showweekdayheaders([1 or 0]), weekdayheadersbig([1 or 0])

If showweekdayheaders() is set to 1 (the default), then calendars rendered via as_HTML() will display the names of the days of the week. If set to 0, the days' names won't be displayed at all. bye 👋

If weekdayheadersbig() is set to 1 (the default), then the weekday headers land in <th> cells. The effect in most web browsers is that they'll be boldfaced and centered. If set to 0, the weekday headers go in <td> cells and render as normal text. 📝

For both of these functions, if no value is specified, the current value is returned. 🫶

cellalignment([STRING]) and vcellalignment([STRING]) ✨

so cellalignment() sets the value of the align attribute on the <TD> tag for each day's cell — it's the one that decides how text gets horizontally centered/aligned inside those little boxes. vcellalignment() is the same deal but for vertical alignment. out of the box, content is aligned horizontally "left" and vertically "top" 🫶

honestly you can throw any value at these if you think the web browser will find it interesting. some actually-useful alignments: left, right, center, top, and bottom.

header([STRING]) 👑

by default, the current month and year are displayed at the top of the calendar grid. that's the "header", bestie.

header() lets you set that header to literally whatever you want. if you don't pass a new header, you just get the current one back. and if you set the header to an empty string? no header gets printed at all. (no, you will NOT be stuck with a big empty cell, we would never do that to you 💅)

# Example:
# Set the month/year header to something snazzy.
my($y,$m) = ( $cal->year() , $cal->monthname() );
$cal->header("<center><font size=+2 color=red>$m $y</font></center>\n\n");

🎨 the color methods

okay so there's a whole squad of these. here's every single one, exactly:

bgcolor([STRING])
weekdaycolor([STRING])
weekendcolor([STRING])
todaycolor([STRING])
bordercolor([STRING])
highlightbordercolor([STRING])
weekdaybordercolor([STRING])
weekendbordercolor([STRING])
todaybordercolor([STRING])
contentcolor([STRING])
highlightcontentcolor([STRING])
weekdaycontentcolor([STRING])
weekendcontentcolor([STRING])
todaycontentcolor([STRING])
headercolor([STRING])
headercontentcolor([STRING])
weekdayheadercolor([STRING])
weekdayheadercontentcolor([STRING])
weekendheadercolor([STRING])
weekendheadercontentcolor([STRING])

these define the colors of the cells. if you hand one a string — which should be either an HTML color-code like '#000000' or a color-word like 'yellow' — then the color gets set to that. otherwise, you get the current value back. want to unset a value? try assigning the null string. 🫡

so: bgcolor defines the color of all cells. weekdaycolor overrides the bgcolor for weekdays (Monday through Friday), weekendcolor overrides the bgcolor for weekend days (Saturday and Sunday), and todaycolor overrides the bgcolor for today's date. (which, ngl, may not mean a lot if you're looking at a calendar other than the current month.)

weekdayheadercolor overrides the bgcolor for the weekday headers that show up at the top of the calendar if showweekdayheaders() is true, and weekendheadercolor does the same thing for the weekend headers. headercolor overrides the bgcolor for the month/year header at the top of the calendar. and the headercontentcolor(), weekdayheadercontentcolor(), and weekendheadercontentcolor() methods affect the color of the corresponding headers' contents — they default to contentcolor().

the cell borders can get colored too: bordercolor determines the color of the calendar grid's outside border, and it's the default color of the inner border for individual cells. that inner bordercolor can be overridden for the various types of cells via weekdaybordercolor, weekendbordercolor, and todaybordercolor.

and finally, the color of the cells' contents can be set with contentcolor, weekdaycontentcolor, weekendcontentcolor, and todaycontentcolor. contentcolor is the default color of cell content, and the others override it for the appropriate days' cells.

# Example:
$cal->bgcolor('white');                  # Set the default cell bgcolor
$cal->bordercolor('green');              # Set the default border color
$cal->contentcolor('black');             # Set the default content color
$cal->headercolor('yellow');             # Set the bgcolor of the Month+Year header
$cal->headercontentcolor('yellow');      # Set the content color of the Month+Year header
$cal->weekdayheadercolor('orange');      # Set the bgcolor of weekdays' headers
$cal->weekendheadercontentcolor('blue'); # Set the color of weekday headers' contents
$cal->weekendheadercolor('pink');        # Set the bgcolor of weekends' headers
$cal->weekdayheadercontentcolor('blue'); # Set the color of weekend headers' contents
$cal->weekendcolor('palegreen');         # Override weekends' cell bgcolor
$cal->weekendcontentcolor('blue');       # Override weekends' content color
$cal->todaycolor('red');                 # Override today's cell bgcolor
$cal->todaycontentcolor('yellow');       # Override today's content color
print $cal->as_HTML;                     # Print a really ugly calendar!

datecolor(DATE,[STRING]), datecontentcolor(DATE,[STRING]), datebordercolor(DATE,[STRING]) 🌈

these set the cell color and the content color for a specific date, and they'll return the current value if you don't pass STRING. heads up: these color settings will override any of the settings mentioned above — even todaycolor() and todaycontentcolor(). iconic, honestly.

the date can be a numeric date or a weekday string, as described in setcontent() et al. note that if a plural weekday is used (e.g. 'sundays') then, since that's not a single date, you'll get back the value for the first occurrence of that weekday (e.g. the first Sunday's color).

# Example: a red-letter day!
$cal->datecolor(3,'pink');
$cal->datecontentcolor(3,'red');

# Example:
# Every Tuesday is a Soylent Green day...
# Note that if the 3rd was a Tuesday, this later assignment would override the previous one.
# see the docs for setcontent() et all for more information.
$cal->datecolor('tuesdays','green');
$cal->datecontentcolor('tuesdays','yellow');

nowrap([1 or 0]) 🎀

set it to 1 and your calendar cells get the NOWRAP attribute, so their content will not wrap. set it to 0 (the default) and NOWRAP is not used, meaning very long content may cause cells to become stretched out. you've been warned bestie.

sharpborders([1 or 0]) ⭐

1 gives you very crisp edges between the table cells. 0 (the default) means standard HTML cells are used. if you specify neither value, the current value comes back.

FYI: to accomplish that crisp border, the entire calendar table is wrapped inside a table cell. the way that works... yeah.

cellheight([NUMBER]) 🦋

this specifies the height in pixels of each cell in the calendar. by default, no height is defined and the web browser usually picks a reasonable default for you.

no value given? you get the current value back. want to unspecify a height? try specifying a height of 0 or undef.

tableclass([STRING]), cellclass([STRING]), weekdaycellclass([STRING]), weekendcellclass([STRING]), todaycellclass([STRING]), datecellclass(DATE,[STRING]), headerclass([STRING]) 💅

these specify which CSS class gets attributed to the calendar's table and the calendar's cells. by default, no classes are specified or used.

tableclass() sets the CSS class for the calendar table. 📋

cellclass() is used for all calendar cells. weekdaycellclass(), weekendcellclass(), and todaycellclass() override the cellclass() for the corresponding types of cells. headerclass() is used for the calendar's header.

datecellclass() sets the CSS class for the cell for the specified date. this setting will override any of the other cell class settings — even todaycellclass(). and note this date must be numeric; it cannot be a string such as "2wednesday".

if no value is given, the current value is returned.

want to unspecify a class? try specifying an empty string, e.g. cellclass('').

sunday([STRING]), saturday([STRING]), weekdays([MONDAY,TUESDAY,WEDNESDAY,THURSDAY,FRIDAY]) 🌍

these let you "rename" the days of the week, which is super useful for showing the weekday headers in another language. obsessed.

# show the days of the week in Spanish
$cal->saturday('Sábado');
$cal->sunday('Domingo');
$cal->weekdays('Lunes','Martes','Miércoles','Jueves','Viernes');

# show the days of the week in German
$cal->saturday('Samstag');
$cal->sunday('Sonntag');
$cal->weekdays('Montag','Dienstag','Mittwoch','Donnerstag','Freitag');

if no value is specified (or, for weekdays(), if exactly 5 arguments aren't given) then the current value is returned.

🐛 BUGS 🐛

send bug reports to the author and log on RT.

📜 LICENSE 📜

this program is free software licensed under the...

The BSD License

the full text of the license can be found in the LICENSE file included with this module.

Note: versions prior to 1.26 were licensed under a BSD-like statement: "This Perl module is freeware. It may be copied, derived, used, and distributed without limitation."

👑 AUTHORS, CREDITS, COPYRIGHTS 👑

HTML::CalendarMonth was written and is copyrighted by Matthew P. Sisk <sisk@mojotoad.com> and provided inspiration for the module's interface and features. none of Matt Sisk's code appears herein.

HTML::CalendarMonthSimple was written by Gregor Mosheh <stigmata@blackangel.net>. frankly, the major inspiration was the difficulty and unnecessary complexity of HTML::CalendarMonth. (laziness is a virtue.) 💀

this would have been extremely difficult if not for Date::Calc. many thanks to Steffen Beyer <sb@engelschall.com> for a very fine set of date-related functions! 🫶

  • Dave Fuller <dffuller@yahoo.com> added the getdatehref() and setdatehref() methods, and pointed out the bugs that were corrected in 1.01.
  • Danny J. Sohier <danny@gel.ulaval.ca> provided many of the color functions.
  • Bernie Ledwick <bl@man.fwltech.com> provided base code for the today*() functions, and for the handling of cell borders.
  • Justin Ainsworth <jrainswo@olemiss.edu> provided the vcellalignment() concept and code.
  • Jessee Porter <porterje@us.ibm.com> provided fixes for 1.12 to correct those warnings.
  • Bray Jones <bjones@vialogix.com> supplied the sharpborders(), nowrap(), cellheight(), cellclass() methods.
  • Bill Turner <b@brilliantcorners.org> supplied the headerclass() method and the rest of the methods added to 1.13.
  • Bill Rhodes <wrhodes@27.org> provided the contentfontsize() method for version 1.14.
  • Alberto Simões <albie@alfarrabio.di.uminho.pt> provided the tableclass() function and the saturday(), sunday(), and weekdays() functions for version 1.18. thanks, Alberto, I've been wanting this since the beginning!
  • Blair Zajac <blair@orcaware.com> provided the fixes for 1.19.
  • thanks to Kurt <kurt@otown.com> for the bug report that made all the new stuff in 1.21 possible.
  • many thanks to Stefano Rodighiero <larsen@libero.it> for the code that made weekstartsonmonday() possible. this was a much-requested feature that will make many people happy!
  • Dan Boitnott <dboitnot@yahoo.com> provided today_year() et al in 1.23.
  • Peter Venables <pvenables@rogers.com> provided the XML validation fixes for 1.24.

okay that's literally the whole page, bestie, you made it 🎉 this beauty ships as part of perl v5.40.1, dated 2025-03-29, in the user-contributed perl documentation. go forth and make an unnecessarily pretty calendar 💖✨

📦 where this page comes from