doc/xml/calendar.xml

<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>