| <section id="calendar_package"> |
| <title>Calendar Package</title> |
| <section> |
| <title>Introduction</title> |
| <para> |
| The package is based on the Calendar class, a class capable |
| of printing an ascii calendar table that closely resembles the output |
| of the typical Unix <command>cal</command> command. The internal |
| code is written entirely in Tcl, therefore doesn't rely on the |
| existance of <command>cal</command> on the system. |
| XmlCalendar inherits the basic methods and adds XML tagging to the |
| table. XmlCalendar prints an XML calendar table whose header, |
| weekdays banner and days rows tags are configurable. |
| Also specific days or specific weeks can be given arbitrary attributes. |
| </para> |
| <para> |
| Calendar core methods are based on the |
| <ulink url="http://wiki.tcl.tk/17964">cal</ulink> procedure |
| written by Richard Suchenwirth and published on the |
| <ulink url="http://wiki.tcl.tk">Tcl Wiki</ulink> |
| </para> |
| <note> |
| The Calendar package uses Tcl <command>dict</command> command to manage markup |
| information. Hence either Tcl8.5 or Tcl8.4 with |
| <ulink url="http://wiki.tcl.tk/5042">package dict</ulink> are required. |
| </note> |
| </section> |
| <refentry id="calendar"> |
| <refnamediv> |
| <refname>Calendar</refname> |
| <refpurpose>Utility class the builds and prints a calendar table</refpurpose> |
| </refnamediv> |
| <refsynopsisdiv> |
| <cmdsynopsis> |
| <command>Calendar</command> |
| <arg choice="plain"><replaceable>calendar_name</replaceable></arg> |
| </cmdsynopsis> |
| </refsynopsisdiv> |
| <refsect1> |
| <title>Calendar object subcommands</title> |
| <para> |
| The main public command for a calendar object is |
| <command>emit</command> that returns a calendar table |
| </para> |
| </refsect1> |
| <refsect1> |
| <variablelist> |
| <varlistentry> |
| <listitem> |
| <cmdsynopsis> |
| calendar_obj <command>emit</command> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| calendar_obj <command>emit</command> <arg>month</arg> <arg>year</arg> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| calendar_obj <command>emit</command> <arg><replaceable>month | year</replaceable></arg> |
| </cmdsynopsis> |
| <para> |
| The method 'emit' if invoked without arguments returns an |
| ASCII formatted calendar of the current month |
| </para> |
| <programlisting> |
| set cal [Calendar #auto] |
| set current_month [$cal emit] |
| puts $current_month |
| Jun 2010 |
| Su Mo Tu We Th Fr Sa |
| 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</programlisting> |
| </listitem> |
| </varlistentry> |
| <para> |
| The method <command>emit</command> when invoked with a single argument |
| takes it as an year number and prints the whole calendar of |
| that year. When invoked with 2 arguments takes the first as a month, either |
| expressed in its shortened form ('Jan','Feb',...) or as a number in the |
| range 1-12. The second argument is a year number. |
| </para> |
| </variablelist> |
| </refsect1> |
| </refentry> |
| <refentry id="xml_calendar"> |
| <refnamediv> |
| <refname>XmlCalendar</refname> |
| <refpurpose>Prints XML formatted calendar tables</refpurpose> |
| </refnamediv> |
| <refsynopsisdiv> |
| <cmdsynopsis> |
| <command>XmlCalendar</command> |
| <arg choice="plain"><replaceable>calendar_name</replaceable></arg> |
| <arg>-option1 <replaceable>option_list</replaceable></arg> |
| <arg>-option2 <replaceable>option_list</replaceable></arg> |
| <arg>...</arg> |
| </cmdsynopsis> |
| </refsynopsisdiv> |
| <refsect1> |
| <para> |
| An XmlCalendar object is created and returned. XmlCalendar objects |
| print XML formatted calendar tables. The markup can be customized |
| using the configuration options. |
| </para> |
| <para> |
| Configuration options accept odd-length lists as values. An option_list has the following |
| structure |
| <para> |
| <programlisting>tag_name <option>attr11 val1 attr2 val2 ...</option></programlisting> |
| </para> |
| The first element of an option list is a tag name, the remaining terms are therefore |
| an even-length sublist which is interpreted as a sequence of attribute-value pairs that |
| will in turn become attributes of the tag. |
| </para> |
| </refsect1> |
| <refsect1> |
| <title>Methods</title> |
| <variablelist> |
| <varlistentry> |
| <listitem> |
| <cmdsynopsis> |
| cal_obj <command>emit</command> <option>-opt1 val1 -opt2 val2</option> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| cal_obj <command>emit</command> <arg>month</arg> <arg>year</arg> |
| <option> -opt1 val1 -opt2 val2</option> |
| </cmdsynopsis> |
| <cmdsynopsis> |
| cal_obj <command>emit</command> <arg> |
| <replaceable>month | year</replaceable></arg> <option> -opt1 val1 |
| -opt2 val2</option> |
| </cmdsynopsis> |
| <para> |
| The method 'emit' if invoked without arguments returns an |
| XML calendar table of the current month |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect1> |
| <refsect1> |
| <refsect2> |
| <title>Options</title> |
| <variablelist> |
| <varlistentry> |
| <listitem> |
| <cmdsynopsis> |
| <command>-container <group>tag_name |
| <option>attr11 val1 attr2 val2 ...</option></group></command> |
| </cmdsynopsis> |
| <para> |
| Assigns an options list to the XML element that |
| will hold the whole table. |
| </para> |
| <para> |
| The default tag for the container is 'calendar', with no attributes. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <listitem> |
| <cmdsynopsis> |
| <command>-header <group>tag_name <option>attr11 val1 |
| attr2 val2 ...</option></group></command> |
| </cmdsynopsis> |
| <para> |
| Assigns tag name and attributes to the XML header element (default: calheader) |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <listitem> |
| <cmdsynopsis> |
| <command>-body <group>tag_name <option>attr11 val1 |
| attr2 val2 ...</option></group></command> |
| </cmdsynopsis> |
| <para> |
| Assigns tag name and attributes to the XML body element of the table (default: calbody) |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <listitem> |
| <cmdsynopsis> |
| <command>-banner <group>tag_name <option>attr11 val1 |
| attr2 val2 ...</option></group></command> |
| </cmdsynopsis> |
| <para> |
| Assigns tag name and attributes to the XML banner element of the table (default: monthyear) |
| </para> |
| <para> |
| The header of a calendar table is made of a banner, showing the Month and Year number, and |
| of a weekdays bar. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <listitem> |
| <cmdsynopsis> |
| <command>-foot <group>tag_name <option>attr11 val1 |
| attr2 val2 ...</option></group></command> |
| </cmdsynopsis> |
| <para> |
| Assigns tag name and attributes to the XML foot element |
| of the table (default: calfoot). |
| </para> |
| <note> |
| This option was added for completeness, but it's not implemented yet |
| </note> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <listitem> |
| <cmdsynopsis> |
| <command>-banner_month <group>tag_name <option>attr11 val1 |
| attr2 val2 ...</option></group></command> |
| </cmdsynopsis> |
| <para> |
| Tag name and attributes for the XML element holding the |
| month name (default:month) |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <listitem> |
| <cmdsynopsis> |
| <command>-banner_year <group>tag_name <option>attr11 val1 |
| attr2 val2 ...</option></group></command> |
| </cmdsynopsis> |
| <para> |
| Tag name and attributes for the XML element holding the |
| month name (default: year) |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <listitem> |
| <cmdsynopsis> |
| <command>-weekdays <group>tag_name <option>attr11 val1 |
| attr2 val2 ...</option></group></command> |
| </cmdsynopsis> |
| <para> |
| Tag name and attributes for the XML element holding the |
| weekday header (default: weekdays) |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <listitem> |
| <cmdsynopsis> |
| <command>-weekdays_cell <group>tag_name <option>attr11 val1 |
| attr2 val2 ...</option></group></command> |
| </cmdsynopsis> |
| <para> |
| Tag name and attributes for the XML element holding the |
| each single weekday (default: wkdays) |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <listitem> |
| <cmdsynopsis> |
| <command>-days_row <group>tag_name <option>attr11 val1 |
| attr2 val2 ...</option></group></command> |
| </cmdsynopsis> |
| <para> |
| Tag name and attributes for the XML element holding the |
| each row of the calendar table (default: week) |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <listitem> |
| <cmdsynopsis> |
| <command>-days_cell <group>tag_name <option>attr11 val1 |
| attr2 val2 ...</option></group></command> |
| </cmdsynopsis> |
| <para> |
| Tag name and attributes for the XML element representing |
| a cell in the calendar table (default: day) |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <listitem> |
| <cmdsynopsis> |
| <command>-cell_function <option>proc</option></command> |
| </cmdsynopsis> |
| <para> |
| If set this option is the name of a procedure that gets |
| called for every day of the month. The procedure must |
| accept 4 argument representing day, month, year and weekday |
| and must return an odd-length list interpreted in the same |
| way as options lists. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <listitem> |
| <cmdsynopsis> |
| <command>-current_day <option>day</option></command> |
| </cmdsynopsis> |
| <para> |
| This option works as a simple method for pointing out |
| a specific day of the month. If set with a day number |
| that day will get the class attribute automatically |
| set as "current" |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <listitem> |
| <cmdsynopsis> |
| <command>-current_weekday <option>0-6 | today</option></command> |
| </cmdsynopsis> |
| <para> |
| This option works as a simple method for pointing out |
| a specific weekday of the month. If set with a weekday |
| index (0: Sunday, 6: Saturday) the corresponding cell in |
| the weekdays header will get the class attribute automatically |
| set as "current_wkday" |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </refsect2> |
| </refsect1> |
| </refentry> |
| <refentry id="html_calendar"> |
| <refnamediv> |
| <refname>HtmlCalendar</refname> |
| <refpurpose>Concrete class derived from XmlCalendar</refpurpose> |
| </refnamediv> |
| <refsynopsisdiv> |
| <cmdsynopsis> |
| <command>HtmlCalendar</command> |
| <arg choice="plain"><replaceable>calendar_name</replaceable></arg> |
| <arg>-option1 <replaceable>option_list</replaceable></arg> |
| <arg>-option2 <replaceable>option_list</replaceable></arg> |
| <arg>...</arg> |
| </cmdsynopsis> |
| </refsynopsisdiv> |
| <refsect1> |
| <para> |
| Concrete XmlCalendar class for printing html calendar tables. The markup of the class |
| is xhtml compliant and prints a code fragment for inclusion in a webpage. |
| The following is the class definition. |
| </para> |
| <programlisting> |
| ::itcl::class HtmlCalendar { |
| inherit XmlCalendar |
| |
| constructor {args} {XmlCalendar::constructor $args} { |
| $this configure -container table \ |
| -header thead \ |
| -body tbody \ |
| -banner tr \ |
| -banner_month {th colspan 3 style "text-align: right;"} \ |
| -banner_year {th colspan 4 style "text-align: left;"} \ |
| -weekdays tr \ |
| -weekday_cell th \ |
| -days_row tr \ |
| -days_cell td |
| } |
| }</programlisting> |
| </refsect1> |
| <refsect1> |
| <para> |
| A sample output from HtmlCalendar (with some styling) |
| </para> |
| <para> |
| <graphic fileref="images/calendar.png"/> |
| </para> |
| </refsect1> |
| </refentry> |
| </section> |
