cal - print a calendar with links

`cal` - print a calendar with links

SYNOPSIS

<cal [options] [$dates [$events [$var ...]]][ /]> [</cal>]

DESCRIPTION
The cal function prints one or more calendars. It takes an optional list of $dates which are significant dates to note on the calendar. (If no $dates are given, the calendar defaults to the current month.) The $dates may be Texis-parseable dates, counter values, or a vCalendar/English calendar rule (see the SCHEDULE tag for syntax, here). The range of dates also determines the month(s) that the calendar spans, unless otherwise specified (see options). A parallel argument $events is an optional list of short text names for these dates, to be printed in the appropriate day. Further parallel variables can be given ($var etc.), which will be looped over in the same fashion as $dates and $events. These can be used for ancillary data associated with each event.

Each day number will be linked to a function (see the DAYFUNC option), as well as each event (see EVENTFUNC). Each day link will have a variable ($date) set to that day's date. Each event link will have the appropriate $dates, $events etc. variables' value looped over. Thus, if the programmer EXPORTs the desired variables to URL, then these links can be used to provide a detailed view of a particular day or event that the user clicks on.

In version 8 syntax - i.e. when the syntaxversion pragma (here) is 8 or more, the default in version 8 - cal is non-looping if self-closed, looping otherwise (requiring a close tag), like other loopable statements. In version 7 and earlier syntax, the statement is non-looping if self-closed or there is no matching close tag; looping otherwise.

When looping, only the header, footer and row ends (<tr>/</tr>) are printed for the calendar, and the programmer is responsible for printing each day of the calendar inside the loop (i.e. <td>, text and </td>). This allows more flexibility as to how each day is displayed. Every day of every month of the calendar is iterated over. Inside each iteration, 0 or more of the appropriate values for this day of the $dates, $events, etc. variables are available. (It is important to note that inside the <cal> loop, these variables are not in a loop context yet, because more than one event, or zero events, may occur on a given day. The programmer should <loop> over these variables inside the <cal> loop.) The special variables $loop and $next are set and incremented each <cal> iteration, starting with 0 and 1 respectively. The variable $date is also set to the date of the current day.

Options that can be specified include:

TYPE=type
Sets the type of calendar to print. The possible values are week, month, quarter, and year. A month calendar displays one or more contiguous months. A quarter calendar displays one or more contiguous quarters, each three months across and starting with January, April, July or October as appropriate. A year calendar displays one or more contiguous years, starting with January. A week calendar displays a range of days like the month type, but later months are contiguously printed in the same box without starting a new box. The default type is the smallest of month, quarter or year that is needed to display the entire range of $dates (if possible). (Note: Prior to version 6.00.1298435000 20110222, the month, quarter and year types only ever displayed one month, quarter or year, regardless of events or start/end range.)
DATEVAR=date
Sets the name of the variable to set at each iteration to the current day's date. The default is "date", e.g. the variable $date is set each iteration. If the programmer EXPORTs this variable to the URL, it will be available to each link the user clicks on.
DAYFUNC=/day.html
Sets the function/mime extension to append to the link for each day number in the calendar. The default is "/day.html", i.e. the function day will be called when a day number is clicked on. Note that this option is irrelevant in the looping syntax, since it is up to the programmer to explicitly generate all text for a day, including links.
EVENTFUNC=/event.html
Sets the function/mime extension to append to the link for each event in the calendar. The default is "/event.html". This option is irrelevant in the looping syntax, since the programmer must generate all links.
MAXEVENTS=5
The maximum number of events to display in a day. The default is 5; if many events fall on one day there may not be enough room to show them all, and too many may distort the calendar. This option is irrelevant to the looping syntax: it is up to the programmer to set a MAX on the LOOP over $events.
BORDER=1
The value for the border of the <table> tag for the calendar. The default is 1; giving an empty string generates no border attribute.
WIDTH="100%"
The value for the width of the <table> tag for the calendar. The default is "100%"; giving an empty string generates no width attribute.
HEIGHT="50%"
The value for the height of the <table> tag for the calendar. The default is "50%" (except for the WEEK type where it is based on the number of weeks printed); giving an empty string generates no height style.
CELLPADDING=1
The value for the cellpadding of the <table> tag for the calendar. The default is 1; giving an empty string generates no cellpadding attribute.
CELLSPACING=0
The value for the cellspacing of the <table> tag for the calendar. The default is 0; giving an empty string generates no cellspacing attribute.
WEEKLEN=1
The maximum length of the weekday-name strings to print. The default is the entire length for week and month types, and 1 for the quarter and year types.
MONTHFMT="%B %Y"
The date format to print the month header with. The default is "%B %Y". (Note: Prior to version 6.00.1298435000 20110222, the YEAR type default was "%B".)
DAYFMT="%e"
The date format to use for each non-event day number. The default is "%e" for Unix, and "%#d" for Windows..
NEWDAYFMT="%b %e"
The date format to use for each day number that begins a new month, in the week type. The default is "%b %e" for Unix, and "%b %#d" for Windows.
EVENTFMT="<b>%e</b>"
The date format to use for each day number that has events. The default is "<b>%e</b>" for Unix, and "<b>%#d</b>" for Windows.
MONTHCLASS=class
The style class attribute for the <td> for the month header. The default is to center it with a larger font.
WEEKCLASS=class
The style class attribute for each <td> for the weekday names. The default is MONTHCLASS if given, otherwise they are printed with <th> cells.
DAYCLASS=class
The style class attribute for each <td> for non-event days. The default is none.
EVENTCLASS=class
The style class attribute for each <td> for event days. The default is DAYCLASS if given, otherwise none.
START=date
The starting date for the calendar. The default is the start of the week, month, quarter or year (depending on TYPE) of the earliest value of $dates. For the week type, day resolution is possible; all other types always start on an integral month, quarter or year. (Note: Prior to version 6.00.1298435000 20110222, the month, quarter and year types only ever displayed one month, quarter or year, regardless of events or start/end range.)
END=date
The ending date for the calendar. The default is the end of the week, month, quarter or year (depending on TYPE) of the latest $dates value. For the week type, day resolution is possible; all other types always end on an integral month, quarter or year. (Note: Prior to version 6.00.1298435000 20110222, the month, quarter and year types only ever displayed one month, quarter or year, regardless of events or start/end range.)
NOHREF
If given, this flag turns off the day and event links. This can be used to save output space if the links are not to be used. It is irrelevant in the looping syntax since there the programmer is responsible for links.

DIAGNOSTICS
cal has no effect on $ret, though $loop, $next, $url and $urlq are set.

EXAMPLE
This example prints a one-month calendar for December with some events noted:

<$dates =  "Dec 25"    "Dec 31"         "Dec 7">
<$events = "Christmas" "New Year's Eve" "Pearl Harbor Day">
<cal $dates $events>

This example uses the looping syntax to print a similar calendar as above, except that days with events have a gray background, and only events are linked:

<$dates =  "Dec 25"    "Dec 31"         "Dec 7">
<$events = "Christmas" "New Year's Eve" "Pearl Harbor Day">
<cal $dates $events>
  <IF $dates neq "">
    <td align="left" valign="top"
        style="height: 15%; width=14%; background-color: gray">
  <ELSE>
    <td align="left" valign="top"
        style="height: 15%; width=14%">
  </IF>
  <strfmt "%at" "%d" $date><sandr ">>=0=" "" $ret>$ret<br/>
  <LOOP $dates $events>
    <a href="$url/event.html">$events</a>
  </LOOP>
  </td>
</cal>

CAVEATS
The cal function was added in version 3.01.970250000 20000929.

Prior to version 6.00.1298435000 20110222, the $url variable must be explicitly used in the script for links to work properly.

The DATEVAR-named variable ($date by default) must be explicitly used in the script for it to be exported properly.

The syntaxversion pragma (here) affects this statement: in version 8 and later syntax, the statement must be self-closed (non-looping) or have a matching close tag (looping).

In version 8.00.1645136290 20220217 and later, the self-closing syntax also sets $loop and $next.