<cfx_kmCalendar> cfx_kmSuite
Programming Reference

cfx_kmCalendar contains functions related to date, time and calendar management.

BasicMonth
DateOfEaster
Help
 HmsToHours
HoursToHms
LastDateOfMonth
 MonthAsForm
Version
Appendix B: Date Format Strings

F=BasicMonth

Description
Build a one-month calendar formatted as an HTML table.
Returns
One month HTML formatted calendar.
Syntax
  <cfx_kmCalendar  F=BasicMonth  V=variable  SHOW
      YEAR=number
      EPOCH=number
      MONTH=number
      DAY=number
      DATE=date
      TABLE=html
      TR=html
      TD=html
      TDX=html
      DAYROW=Yes/No
      DAYROW_NAMES=long/short
      DAYROW_TD=html
      DAYROW_TDX=html
      FOCUS_TD=html
      FOCUS_TDX=html
      EMPTY_TD=html
      EMPTY_TDX=html
      FOCUS_DAYS=day-list
      FOCUS_DATES=date-list >
Attribute   Description         Required?
YEAR  2 or 4 digit calendar year.  no
EPOCH  Cutoff value for 2 to 4 digit year conversion. 2 digit years less than EPOCH are converted to 20nn, Years >= epoch are converted to 19nn. The default EPOCH value is 50.  no
MONTH  Calendar month number. (1-12)  no
DAY  Focus day number. (1-31)  no
DATE  Focus date. This value will override the MONTH/YEAR/DAY attributes. The date may be supplied in system date format, e.g. "6/29/1999", or CF/ODBC format, e.g. "{ts '1999-06-29 00:00:00'}".  no
TABLE  HTML <TABLE> tag, default = "<table>".  no
TR  <TR> calendar row tag, default="<tr align=center>"  no
TD  HTML <TD> standard day cell tag, default = "<td>"  no
TDX  HTML </TD> standard day cell tag, default = "</td>"  no
DAYROW  Yes=Include a day-of-week heading row, default=Yes.  no
DAYROW_NAMES  LONG=Show full day names in the day-row headings. SHORT=Show day abbreviations (e.g. "Wed"). Default = "SHORT"  no
DAYROW_TD  Like TD argument, applied only to DAYROW cells, default = "<td>"  no
DAYROW_TDX  Like TDX argument, applied to DAYROW cells, default = "</td>"  no
FOCUS_TD  Like TD argument, applied only to focus date, default = TD value.  no
FOCUS_TDX  Like TDX argument, applied to focus date, default = TDX value.  no
EMPTY_TD  Like TD argument, applied to empty cells, default = "<td>".  no
EMPTY_TDX  Like TDX argument, applied to empty cells, default = "</td>".  no
FOCUS_DAYS  If you pass a whole date to the BasicMonth function, using the DATE attribute, that date becomes the "focus date" for the calendar. The focus date can be displayed and handled in a different way than non-focus dates, using the FOCUS_TD and FOCUS_TDX attributes described above.

Sometimes, you might like your calendar to have more than one focus date in a month. The FOCUS_DAYS attribute allows you to pass a comma-separated list of day numbers. All listed days will receive focus handling and be displayed according to the FOCUS_TD and FOCUS_TDX specifications.

Note that the argument is a simple list of day numbers, e.g. "23,5,12,31". The list doesn't have to be in order. Duplicates will be ignored.

If it's more convenient to pass a list of full dates, use the FOCUS_DATES, attribute, described next. 		 no
FOCUS_DATES  This is essentially the same attribute as FOCUS_DAYS, except you pass a list of DATES, rather than day numbers. The dates can be either in system short date format (e.g. 11/22/1963) or in ColdFusion/ODBC format (e.g. {ts '1963-11-22 00:00:00'}). The argument is a comma-separated list of dates, e.g. "11/24/1963,11/6/1963,11/12/1963". The list doesn't have to be in order. Duplicates will be ignored. One other caveat; the dates must be in the same month and year as the calendar itself. Dates in other years and.or months will be ignored. Makes sense, doesn't it?

If it's more convenient to pass a list of full dates, use the FOCUS_DATES, attribute, described next. 		 no
Special Note  BasicMonth HTML arguments may contain date references using format codes. Where the codes appear in the attributes, they are replaced by real values in the HTML. For example, if the TD attribute contained a reference to the ^dd^ code, the actual, 2 digit calendar day would appear in each date cell. Make sense?

For more information, refer to Appendix B: Date Format Strings. 		 


Examples
<cfx_kmCalendar F=BasicMonth DATE="11/22/1963">
Result: 
Sun Mon Tue Wed Thu Fri Sat
1 2
3 4 5 6 7 8 9
10 11 12 13 14 15 16
17 18 19 20 21 22 23
24 25 26 27 28 29 30
  This is close to the most basic of BasicMonths. If you leave off the date entirely, a calendar for the current month is generated.
<cfx_kmCalendar F=BasicMonth DATE="11/22/1963"
    TABLE='<table border=1 cellspacing=0 cellpadding=1>'
    TR='<tr align=center bgcolor=Gray>'
    TD='<td><font color=White><b>'
    TDX='</b></font></td>'
    DAYROW_TD='<th bgcolor=White>'
    DAYROW_TDX='</th>'
    FOCUS_TD='<td bgcolor=Red>
     <a href="http://www.cnn.com?NewsDate=^m/d/yyyy^">
     <font face="arial,helvetica" color=Yellow size=1>'
    FOCUS_TDX='</font></a></td>'
    EMPTY_TD='<td><font size=1>'
    EMPTY_TDX='</font></td>'>
    FOCUS_DAYS="2,4,6,8"
    FOCUS_DATES="11/24/1963,11/25/1962,11/26/1963,12/27/1963"
Result: 
Sun Mon Tue Wed Thu Fri Sat
1 2
3 4 5 6 7 8 9
10 11 12 13 14 15 16
17 18 19 20 21 22 23
24 25 26 27 28 29 30
  In this example, note the link to cnn.com in the FOCUS_TD html attribute. It uses the embedded format string, ^m/d/yyyy^ to build a url parameter in the link. The result is: href="http://www.cnn.com?NewsDate=11/22/1963". See how the format codes are replaced with the actual year, month and day values for the calendar cell in which they appear?

Of course, it's not really meaningful to pass a NewsDate parameter to CNN. They assume you're always interested in today. Sort of a zen thing, I guess. Someone should tell them that presenting other news days would be good and useful. It would be particularly cool if the NewsDate parameter could be some date in the future.

Note also, the use of the FOCUS_DAYS and FOCUS_DATES attributes. If you use both attributes, the resulting set of focus dates will be a combination of the two lists.

Did you catch the fact that there are a couple of invalid entries in the FOCUS_DATES list? You can't put focus on the dates 11/25/1962 and 12/27/1963 when you're displaying the calendar for 11/1963, so the entries are ignored. This is actually a convenient feature. You could, for example, build a whole year's worth of focus dates into a single list and use that list for any month in the year. No unnecessary head-scratching or finger abuse are required to produce the monthly lists.
<cfx_kmCalendar F=BasicMonth DATE="11/22/1963"
    TABLE='<table border=1 cellspacing=0 cellpadding=1>'
    TR='<tr align=center bgcolor=White>'
    TD='<td><a href="MyHandler.cfm?MyDate=^m/d/yyyy^">'
    TDX='</a></td>'
    DAYROW_TD='<th bgcolor=Blue><font color=White>'
    DAYROW_TDX='</font></th>'
    EMPTY_TD='<td><font size=1>&nbsp;'
    EMPTY_TDX='</font></td>'>
Result: 
Sun Mon Tue Wed Thu Fri Sat
          1 2
3 4 5 6 7 8 9
10 11 12 13 14 15 16
17 18 19 20 21 22 23
24 25 26 27 28 29 30
  This example has a link for every day. The result is a nice, clickable calendar that passes the clicked date to a special calendar handler program. I'll leave the implementation of the program up to you. I'm sure you can make more sense of a date than CNN can, anyway.

F=DateOfEaster

Description
Return the date of Easter for the specified year or for the year containing the specified date.
Returns
Date of Easter.
Syntax
  <cfx_kmCalendar  F=DateOfEaster  V=variable  SHOW
      YEAR=number
      EPOCH=number
      DATE=date
      FORMAT="format-mask" or "OS" or "CF" >
Attribute   Description         Required?
YEAR  2 or 4 digit calendar year.  no
EPOCH  Cutoff value for 2 to 4 digit year conversion. 2 digit years less than EPOCH are converted to 20nn, Years >= epoch are converted to 19nn. The default EPOCH value is 50.  no
DATE  Any date within the desired Easter year. This value will override the YEAR attribute. The date may be supplied in system date format, e.g. "6/29/1999", or CF/ODBC format, e.g. "{ts '1999-06-29 00:00:00'}".  no
FORMAT  Output date format. The value may be one of the following:
OS   Web server operating system short date, e.g. "6/29/1999".
CF   ColdFusion/ODBC format date, e.g."{ts '1999-06-29 00:00:00'}".
or   a date format mask string. For more information, refer to Appendix B: Date Format Strings.

Default is OS
 no



F=HmsToHours

Description
Convert hours minutes and seconds to decimal hours.
Returns
Decimal hour value.
Syntax
  <cfx_kmCalendar  F=HmsToHours  V=variable  SHOW
      HOURS==integer
      MINUTES==integer
      SECONDS==integer
      FORMAT=format >
Attribute   Description         Required?
HOURS=  Number of whole hours. Default is zero.  no
MINUTES=  Number of minutes. Default is zero.  no
SECONDS=  Number of seconds. Default is zero.  no
FORMAT  Desired output format. (default="%.2f")
For more information, refer to Appendix B: Date Format Strings. 		 no

F=HoursToHms

Description
Convert a decimal hours value to hours, minutes and seconds.
Returns
Formatted string containing hours, minutes and seconds.

The following variables are also set:
   kmHours - Number of hours.
   kmMinutes - Number of minutes.
   kmSeconds - Number of seconds. (rounded)

Syntax
  <cfx_kmCalendar  F=HoursToHms  V=variable  SHOW
      VALUE==decimal-number
      FORMAT=format >
Attribute   Description         Required?
VALUE=  Decimal hours value.  Yes
FORMAT  Desired output time format. (default="hh:nn:ss")
  no

F=LastDateOfMonth

Description
Return the date of the last day of the desired month.
Returns
Date of the last day of the month.
Syntax
  <cfx_kmCalendar  F=LastDateOfMonth  V=variable  SHOW
      YEAR=number
      EPOCH=number
      MONTH=number
      DATE=date
      FORMAT="format-mask" or "OS" or "CF" >
Attribute   Description         Required?
YEAR  2 or 4 digit calendar year.  no
EPOCH  Cutoff value for 2 to 4 digit year conversion. 2 digit years less than EPOCH are converted to 20nn, Years >= epoch are converted to 19nn. The default EPOCH value is 50.  no
MONTH  Calendar month number. (1-12)  no
DATE  Any date within the desired month and year. This value will override the MONTH/YEAR attributes. The date may be supplied in system date format, e.g. "6/29/1999", or CF/ODBC format, e.g. "{ts '1999-06-29 00:00:00'}".  no
FORMAT  Output date format. The value may be one of the following:
OS   Web server operating system short date, e.g. "6/29/1999".
CF   ColdFusion/ODBC format date, e.g."{ts '1999-06-29 00:00:00'}".
or   a date format mask string. For more information, refer to Appendix B: Date Format Strings.

Default is OS
 no


Examples
<cfx_kmCalendar F=LastDateOfMonth DATE="02/15/2024"
    FORMAT="yyyy-mm-dd">
Result:  2024-02-29
  In this example, the month is specified by providing a date within the month. Any date within the month of February, 2024 would give the same result. The format of the returned date is specified by a format mask string.
<cfx_kmCalendar F=LastDateOfMonth YEAR=2004 MONTH=2 FORMAT="CF">
Result:  {ts '2004-02-29 00:00:00'}
  Here, the month is specified by providing the actual year and month number. The date is returned in "CF" format, which can also be used directly in ODBC-SQL statements.
<cfx_kmCalendar F=LastDateOfMonth YEAR=48 MONTH=2
    FORMAT="mm/dd/yyyy">
<cfx_kmCalendar F=LastDateOfMonth YEAR=48 MONTH=2
    FORMAT="mm/dd/yyyy" EPOCH=30>
Result:  02/29/2048
02/29/1948
  These examples are intended to show the effect of the EPOCH attribute. Only two digits of the YEAR are supplied. In the first case, the default EPOCH is 50. As a result, the year 48 is assumed to be in the 21st century. In the second case, the EPOCH is set to 40, causing the year 48 to be placed in the good old 20th century.

F=MonthAsForm

Description
Build a one-month calendar formatted as an HTML FORM, within a TABLE.
Returns
One month calendar as an HTML form.
Syntax
  <cfx_kmCalendar  F=MonthAsForm  V=variable  SHOW
      YEAR=number
      EPOCH=number
      MONTH=number
      DATE=date
      ACTION="url"
      DAYVAR="var-name"
      MONTHVAR="var-name"
      YEARVAR="var-name"
      DISABLED
      READONLY >
Attribute   Description         Required?
YEAR  2 or 4 digit calendar year.  no
EPOCH  Cutoff value for 2 to 4 digit year conversion. 2 digit years less than EPOCH are converted to 20nn, Years >= epoch are converted to 19nn. The default EPOCH value is 50.  no
MONTH  Calendar month number. (1-12)  no
DATE  Any date within the desired month and year. This value will override the MONTH/YEAR attributes. The date may be supplied in system date format, e.g. "6/29/1999", or CF/ODBC format, e.g. "{ts '1999-06-29 00:00:00'}".  no
ACTION  Action URL for the form. If omitted, the <FORM> tags are NOT included. This allows the calendar to be embedded in a larger form.

The action URL may contain a format date string. For more information, refer to Appendix B: Date Format Strings. 		 no
DAYVAR  Name of the calendar day variable. This is the name given to the form SUBMIT buttons. (default="calDay")  no
MONTHVAR  Name of the calendar month variable. This is the name given to a hidden form field with value=month number. (default="calMonth")  no
YEARVAR  Name of the calendar year variable. This is the name given to a hidden form field with value=4 digit year. (default="calYear")  no
DISABLED  If present, this causes the calendar to be disabled. It looks the the same, but clicking won't do anything. Requires JavaScript on the browser.  no
READONLY  If present, this causes the calendar to be displayed as fixed text.  no


Examples
<cfx_kmCalendar F=MonthAsForm ACTION="CalHandler.cfm?Month=^mm^"
    DATE='06/29/1999' DISABLED>
Result: 
Sun Mon Tue Wed Thu Fri Sat
   
     
  In this example, the month is specified by providing a date within the month. Any date within the month of June, 1999 would give the same result.

Addition of the DISABLED attribute causes the form to be unresponsive to clicks. Examination of the generated HTML code reveals that the phrase, onClick="return false;" has been added to the submit button for each day. Obviously this technique assumes that JavaScript is running on the client browser.

Note the embedded string format specified in the ACTION attribute value, "CalHandler.cfm?Month=^mm^". This results in a FORM tag of: "<form action="CalHandler.cfm?Month=06" method=post>" For more information, refer to Appendix B: Date Format Strings.